Requests: HTTP para Humanos¶

Requests é uma biblioteca HTTP licensiada sob Apache2, escrita em Python, para seres humanos.

O módulo urllib2, parte da biblioteca padrão do Python, oferece a maioria das funcionalidades do protocolo HTTP que você precisa, mas a API está completamente quebrada. Ela foi feita para uma época diferente — e uma web diferente. Ela demanda uma enorme quantidade de trabalho (inclusive para sobrescrever métodos) para realizar as tarefas mais simples.

As coisas não deveriam ser desse jeito. Não em Python.

>>> r = requests.get('https://api.github.com/user', auth=('user', 'pass'))
>>> r.status_code
200
>>> r.headers['content-type']
'application/json; charset=utf8'
>>> r.encoding
'utf-8'
>>> r.text
u'{"type":"User"...'
>>> r.json()
{u'private_gists': 419, u'total_private_repos': 77, ...}

Veja um código similiar, sem Requests.

Requests retira todo o trabalho do protocolo HTTP/1.1 do Python - deixando a integração dos seus serviços web sem problemas. Não há necessidade para adicionar query string nas suas URLs manualmente, ou de codificar seus dados de formulário POST. Keep-alive e gerência de conexões HTTP são 100% automáticas, feitas com urllib3, que está incluso no Requests.

Depoimentos¶

O Governo de Sua Majestade, Amazon, Google, Twilio, Mozilla, Heroku, PayPal, NPR, Obama for America, Transifex, Native Instruments, The Washington Post, Twitter, SoundCloud, Kippt, Readability, e Institutos Federais dos Estados Unidos usam Requests internamente. Requests já foi baixado mais de 2 milhões de vezes pelo PyPI.

Armin Ronacher: Requests é o exemplo perfeito de como uma API pode ser bonita com o nível certo de abstração.
Matt DeBoard: Eu vou tatuar o módulo Python do @kennethreitz no meu corpo, de algum jeito. Ele todo.
Daniel Greenfeld: Refiz uma biblioteca com 1200 linhas de código spaghetti com 10 linhas de código graças ao módulo requests do @kennethreitz. Hoje foi SENSACIONAL.
Kenny Meyers: HTTP em Python: Com dúvidas, sem dúvidas, use Requests. Bonito, simples, Pythônico.

Funcionalidades¶

Requests está pronto para a web de hoje.

Domínios e URLs internacionais
Keep-Alive e pooling de conexões
Sessões com persistência de cookies
Verificação SSL igual aos browsers
Autenticação com métodos Basic/Digest
Cookies com chave/valor elegantes
Descompressão automática
Corpos de resposta Unicode
Uploads de arquivos
Tempo máximo de conexões
Suporte a .netrc
Python 2.6-3.3
Thread-safe.

Guia do Usuário¶

Esta parte da documentação, que é principalmente prosa, começa com algumas informações sobre o Requests e então foca em instruções passo-a-passo para aproveitar o máximo do Requests.

Introdução¶

Filosofia¶

Requests foi desenvolvido com alguns conceitos da PEP 20 em mente.

Bonito é melhor do que feio.
Explícito é melhor que implícito.
Simples é melhor que complexo.
Complexo é melhor que complicado.
Legibilidade conta.

Todas as contribuições para Requests deve manter essas regras importantes em mente.

Licensa Apache2¶

Um grande número de projetos open source que você encontra hoje são distruibuídos sob a Licensa GPL. Enquanto a GPL tem seu tempo e lugar, certamente não deve ser a primeira licensa que você recorre para seu próximo projeto open source.

Um projeto que é lançado como GPL não pode ser usado em nenhum produto comercial enquanto o produto não tiverem seu código aberto.

As licensas MIT, BSD, ISC e Apache2 são ótimas alternativas para a GPL que permitem que seu software open-source seja usado livremente em software proprietário de código fechado.

Requests é liberado sob os termos da Licensa Apache2.

Licensa do Requests¶

Copyright 2013 Kenneth Reitz

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Instalação¶

Esta parte da documentação cobre a instalação de Requests. O primeiro passo para usar qualquer pacote de software é instalá-lo corretamente.

Distribute e Pip¶

Instalar requests é simples usando pip:

$ pip install requests

ou, usando easy_install:

$ easy_install requests

Porém, você realmente não deve fazer isso.

Cheeseshop Mirror¶

Se o Cheeseshop estiver fora do ar, você pode instalar Requests usando um dos mirrors. Crate.io é um deles:

$ pip install -i http://simple.crate.io/ requests

Usando o código¶

Requests é desenvolvido ativamente no GitHub, onde o código está sempre disponível.

Você pode clonar o repositório público:

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

Baixar o arquivo tar:

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

Ou, baixar o arquivo zip:

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

Uma vez que você tiver uma cópia do código, você pode incluí-lo no seu pacote Pytohn, ou instalá-lo no seu diretório site-packages facilmente:

$ python setup.py install

Guia de início rápido¶

Ansioso para começar? Esta página dá uma boa introdução em como começar a usar Requests. Ela assume que você já tem Requests instalado. Se você não tem, veja a seção sobre Instalação.

Primeiramente, certifique-se de que:

Requests está instalado
Requests está atualizado

Vamos começar com alguns exemplos simples.

Fazer uma requisição¶

Fazer uma requisição com Requests é muito simples.

Comece importando o módulo Requests:

>>> import requests

Agora, vamos tentar baixar uma página da web. Para este exemplo, vamos baixar a timeline pública do GitHub:

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

Agora, nós temos um objeto Response chamado r. Nós podemos pegar todas as informações que precisamos desse objeto.

A API simples de Requests significa que todas as formas de requisição HTTP são óbvias. Por exemplo, este é o jeito que se faz uma requisição HTTP POST:

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

Legal, né? Que tal outros tipos de requisições HTTP: PUT, DELETE, HEAD e OPTIONS? São todas igualmente simples:

>>> 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")

Está tudo muito bem, mas também é só o começo do que Requests pode fazer.

Passando parâmetros em URLs¶

Você geralmente quer mandar algum tipo de dado na query string da URL. Se você estivesse construindo a URL manualmente, este dado seria dado como pares chave/valor na URL após um ponto de interrogação, por exemplo httpbin.org/get?key=val. Requests permite que você forneça estes argumentos como um dicionário, usando o argumento params. Por exemplo, se você quisesse passar key1=vaue1 e key2=value2 para httpbin.org/get, você usaria o seguinte código:

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

Você pode ver que a URL foi corretamente gerada imprimindo a URL:

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

Conteúdo da resposta¶

Nós podemos ler o conteúdo da resposta do servidor. Considerando a timeline do GitHub novamente:

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

Requests irá automaticamente decodificar o conteúdo do servidor. A maioria dos conjuntos de caracteres unicode são decodificados nativamente.

Quando você faz uma requisição, Requests advinha qual a codificação da reposta baseada nos cabeçalhos HTTP. A codificação de texto advinhada por Requests é usada quando você acessa r.text. Você pode descobrir qual codificação Requests está usando, e mudá-la, utilizando a propriedade r.enconding:

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

Se você mudar a codificação, Requests irá usar o novo valor de r.enconding sempre que você chamar r.text.

Requests também usará codificações personalizadas na ocasião de você precisar delas. Se você criou sua própria codificação e a registrou com o módulo codecs, você pode simplesmente usar o nome do codec como valor de ``r.enconding `` e Requests irá cuidar da decodificação para você.

Resposta binária¶

Você pode acessar o corpo da resposta como bytes, para requisições que não são textos:

>>> r.content
b'[{"repository":{"open_issues":0,"url":"https://github.com/...

As codificações de transferências gzip e deflate são decodificadas automaticamente para você.

Por exemplo, para criar uma imagem de dados binários retornados por uma requisição, você pode usar o seguinte código:

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

Respota JSON¶

Também existe um decodificador JSON integrado, no caso de você lidar com dados JSON:

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

No caso da decodificação do JSON falhar, r.json levanta uma exceção. Por exemplo, se a resposta tem código 401 (Não autorizado), tentar usar r.json levanta Value Error: No JSON objecto could be decoded

Resposta crua¶

No caso raro de você querer recuperar a resposta crua do socket vinda do servidor, você pode acessar r.raw. Se você quiser fazer isto, certifique-se de que você definiu stream=True na sua requisição inicial. Uma vez que você fizer, poderá utilizar:

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

Cabeçalhos personalizados¶

Se você quiser adicionar cabeçalhos HTTP para uma requisição, simplesmente passe-os em um dict para o parâmetro headers.

Por exemplo, nós não especificamos o content-type no exemplo anterior:

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

Requisições POST mais complicadas¶

Tipicamente, você quer enviar algum dado em forma de formulário - assim como um formulário HTML. Para fazer isto, simplesmente passe um dicionário para o argumento data. O seu dicionário de dados será automaticamente formatado como formulário e a requisição é feita:

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

Existem várias ocasiões que você quer enviar dados que não estejam como formulário. Se você passar uma string em vez de um dict, o dado será enviado diretamente.

Por exemplo, a API v3 do GitHub aceita dados codificados como JSON em POST/PATCH:

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

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

POST de arquivo Multipart¶

Requests simplifica o upload de arquivos codificados Multipart:

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

>>> r = requests.post(url, files=files)
>>> r.text
{
  ...
  "files": {
    "file": "<dados...binários...censurados>"
  },
  ...
}

Você pode definir o nome do arquivo explicitamente:

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

>>> r = requests.post(url, files=files)
>>> r.text
{
  ...
  "files": {
    "file": "<dados...binários...censurados>"
  },
  ...
}

Se você quiser, você pode enviar strings para serem recebidas como arquivos:

>>> 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": "algum,dado,para,enviar\\noutra,linha,para,enviar\\n"
  },
  ...
}

Código do status da resposta¶

Você pode verificar o código do status da resposta:

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

Requests também vem com um objeto de referência de códigos de status integrado:

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

Se nós fizermos uma requisição mal-feita (resposta que não tenha código 200), podemos levantar uma exceção usando 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

Mas, já que nosso status_code para r foi 200, quando nós chamamos raise_for_status(), recebemos:

>>> r.raise_for_status()
None

Está tudo bem

Cabeçalhos da resposta¶

Nós podemos visualizar os cabeçalhos da resposta do servidor usando um dicionário 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; charset=utf-8'
}

No entanto, o dicionário é especial: ele é feito sometendo para cabeçalhos HTTP. De acordo com a RFC 2616, cabeçalhos HTTP são case-insensitive.

Assim, nós podemos acessar os cabeçalhos usando qualquer capitalização que quisermos:

>>> r.headers['Content-Type']
'application/json; charset=utf-8'

>>> r.headers.get('content-type')
'application/json; charset=utf-8'

Se um cabeçalho não existe no objeto Response, seu valor padrão é None:

>>> r.headers['X-Random']
None

Cookies¶

Se uma resposta contém alguns cookies, você tem acesso rápido a eles:

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

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

Para enviar seus próprios cookies par ao servidor, você pode usar o parâmetro cookies:

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

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

Redirecionamento e Histórico¶

Requests irá automaticamente realizar redirecionamentos quando utilizados os verbos GET e OPTIONS.

GitHub redireciona todas as requisições HTTP para HTTPS. Nós podemos usar o método history do objeto Response para acompanhar o redirecionamento. Vamos ver o que o GitHub faz:

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

A lista Response.history contém uma lista de objetos Request que foram criados para completar a requisição. A lista é ordenada da requisição mais antiga para a mais nova.

Se você estiver usando GET ou OPTIONS, você pode desabilitar o redirecionamento com o parâmetro allow_redirects:

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

Se você estiver usando POST, PUT, PATCH, DELETE ou HEAD, você pode habilitar o redirecionamento também:

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

Timeouts¶

Você pode dizer para as requisições pararem de esperar por uma resposta depois de um dado número de segundos com o parâmetro 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)

Note:

timeout somente afeta o processo da conexão, não o download do corpo da resposta.

Erros e Exceções¶

Na ocasião de um problema de rede (por exemplo, falha de DNS, conexão recusada, etc.), Requests irá levantar uma exceção ConnectionError.

Na ocasião de uma rara resposta HTTP inválida, Requests irá levantar uma exceção HTTPError.

Se uma requisição excede o tempo limite, uma exceção Timeout é levantada.

Se uma requisição excede o número máximo de redirecionamentos configurado, uma exceção TooManyRedirects é levantada.

Todas as exceções levantadas explicitamente pelo Requests são herdadas de requests.exceptions.RequestException.

Ready for more? Check out the advanced section.

Uso avançado¶

Este documento cobre algumas funcionalidades mais avançadas do Requests.

Objetos Session¶

O objeto Session permite você persistir alguns parâmetros através de requisições. Ele também permite persistência de cookies através de todas as requisições feitas a partir de uma instância de Session.

Um objeto de sessão contém todos métodos da API principal de Requests.

Vamos persistir alguns cookies através de requisições:

s = requests.Session()

s.get('http://httpbin.org/cookies/set/sessioncookie/123456789')
r = s.get("http://httpbin.org/cookies")

print r.text
# '{"cookies": {"sessioncookie": "123456789"}}'

Sessões também podem ser usadas para prover dados padrões para os métodos de requisição. Isto é feito fornecendo dados para as propriedades de um objeto session:

s = requests.Session()
s.auth = ('user', 'pass')
s.headers.update({'x-test': 'true'})

# ambos 'x-test' e 'x-test2' são enviados
s.get('http://httpbin.org/headers', headers={'x-test2': 'true'})

Quaisquer dicionários que você passar para um método de requisição será usado em conjuntos com os valores determinados no nível da sessão. Os parâmetros no nível do método sobrescrevem quaisquer parâmetros de sessão.

Remover um valor de um parâmetro de dicionário

Algumas vezes você gostaria omitir chaves do dicionário da sessão. Para fazer isto, basta definir o valor desta chave como None no parâmetro do método. Ele será omitido automaticamente.

Todos os valores contidos dentro de uma sessão estão disponíveis diretamente para você. Veja a documentação da API Session para saber mais.

Objetos Request e Response¶

Sempre que uma chamada é feita para requests.*() você está fazendo basicamente duas coisas. Primeiro, você está construindo um objeto Request que será enviado para um servidor para realizar a requisição de algum recurso. Segundo, um objeto Response é gerado assim que requests obtém uma resposta do servidor. O objeto de resposta contém todas as informações retornadas pelo servidor e também contém o objeto Request que você criou primeiro. Aqui está uma simples requisição para pegar alguma informação importante dos servidores da Wikipedia:

>>> r = requests.get('http://en.wikipedia.org/wiki/Monty_Python')

Se quisermos acessar os cabeçalhos enviados pelo servidor, nós fazemos isso:

>>> r.headers
{'content-length': '56170', 'x-content-type-options': 'nosniff', 'x-cache':
'HIT from cp1006.eqiad.wmnet, MISS from cp1010.eqiad.wmnet', 'content-encoding':
'gzip', 'age': '3080', 'content-language': 'en', 'vary': 'Accept-Encoding,Cookie',
'server': 'Apache', 'last-modified': 'Wed, 13 Jun 2012 01:33:50 GMT',
'connection': 'close', 'cache-control': 'private, s-maxage=0, max-age=0,
must-revalidate', 'date': 'Thu, 14 Jun 2012 12:59:39 GMT', 'content-type':
'text/html; charset=UTF-8', 'x-cache-lookup': 'HIT from cp1006.eqiad.wmnet:3128,
MISS from cp1010.eqiad.wmnet:80'}

Contudo, se quisermos acessar os cabeçalhos que nós mandamos para o servidor, nós simplesmente acessamos a requisição e, então, os cabelhos da requisição:

>>> r.request.headers
{'Accept-Encoding': 'identity, deflate, compress, gzip',
'Accept': '*/*', 'User-Agent': 'python-requests/1.2.0'}

Requisições preparadas¶

Sempre que você recebe um objeto Response de uma chamada da API ou de Session, o atributo request é, na verdade, o objeto PreparedRequest que foi utilizado. Em alguns casos, você pode querer realizar algum trabalho extra no corpo ou nos cabeçalhos (ou qualquer outra coisa, na verdade) antes de enviar uma requisição. A receita simples para isto é a seguinte:

from requests import Request, Session

s = Session()
prepped = Request('GET',  # ou qualquer outro método, 'POST', 'PUT', etc.
                  url,
                  data=data
                  headers=headers
                  # ...
                  ).prepare()
# faça algo com prepped.body
# faça algo com prepped.headers
resp = s.send(prepped,
              stream=stream,
              verify=verify,
              proxies=proxies,
              cert=cert,
              timeout=timeout,
              # etc.
              )
print(resp.status_code)

Como você não está fazendo nada de especial com o objeto Request, você o preparou imediatamente e modificou o objeto PreparedRequest. Então, este com os outros parâmetros que você mandaria com requests.* ou Session.*.

Verificação de certificado SSL¶

Requests pode verificar certificados SSL para requisições HTTPS, assim como um navegador. Para conferir um certificado SSL de um host, você usar o argumento verify:

>>> requests.get('https://kennethreitz.com', verify=True)
requests.exceptions.SSLError: hostname 'kennethreitz.com' doesn't match either of '*.herokuapp.com', 'herokuapp.com'

Eu não tenho configuração SSL neste domínio, então ele falha. Excelente. GitHub tem, no entanto:

>>> requests.get('https://github.com', verify=True)
<Response [200]>

Você também pode passar para verify o caminho para um arquivo CA_BUNDLE para certificados privados. Você também pode definir a variável de ambiente REQUESTS_CA_BUNDLE.

Requests também pode ignorar a verificação do certificado SSL se você definir verify como False.

>>> requests.get('https://kennethreitz.com', verify=False)
<Response [200]>

Por padrão, verify está definido como True. A opção verify é somente aplicada para certificados de hosts.

Você também pode especificar um certificado local para ser usado como certificado do lado do cliente, como um único arquivo (contendo a chave privada e o certificado) ou como uma tupla do caminho de ambos arquivos:

>>> requests.get('https://kennethreitz.com', cert=('/path/server.crt', '/path/key'))
<Response [200]>

Se você especificar um caminho errado ou um certificado inválido:

>>> requests.get('https://kennethreitz.com', cert='/wrong_path/server.pem')
SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib

Fluxo do conteúdo do corpo¶

Por padrão, quando você faz uma requisição, o corpo da resposta é baixado imediatamente. Você pode mudar este comportamento e prevenir o download do corpo da resposta até que você acesse o atribute Response.content com o parâmetro stream:

tarball_url = 'https://github.com/kennethreitz/requests/tarball/master'
r = requests.get(tarball_url, stream=True)

Neste ponto, apenas os cabeçalhos das respostas forão baixados e a conexão continua aberta, nos permitindo a recuperação condicional do conteúdo:

if int(r.headers['content-length']) < TOO_LONG:
  content = r.content
  ...

Você pode então controlar o fluxo com o uso dos métodos Response.iter_content e Response.iter_lines, ou lendo do objeto subjacente da urllib3 urllib3.HTTPResponse em Response.raw.

Keep-Alive¶

Excelente novidades - graças à urllib3, keep-alive é 100% automático dentro de uma sessão! Todas as requisições que forem feitas dentro de uma sessão irão automaticamente reusar a conexão apropriada!

Note que conexões são somente liberadas de volta para o pool para serem reusadas uma vez que você todos os dados do corpo foram lidos; certifique-se de definir stream para False ou de ler a propriedade content do objeto Response.

Uploads com Streaming¶

Requests suporta uploads com streaming, que permitem que você mande grandes streams ou arquivos sem precisar carregá-los na memória. Para stream e upload, simplesmente forneça um objeto do tipo de arquivo para o corpo:

with open('massive-body') as f:
    requests.post('http://some.url/streamed', data=f)

Requisições com blocos codificados¶

Requests também suporta codificação de transferência em bloco para requisições de saída e de entrada. Para mandar uma requisição com um bloco codificado, simplesmente forneça um gerador (ou qualquer iterador sem tamanho) para o corpo:

def gen():
    yield 'olá'
    yield 'você'

requests.post('http://some.url/chunked', data=gen())

Hooks de eventos¶

Requests tem um sistema de hooks que você pode usar para manipular pedaços do processo de requisição, ou tratamento de eventos de sinais.

Hooks disponíveis:

response:: A resposta gerada por um objeto Request.

Você pode atribuir uma função de hook para cada request passando um dicionário {hook_name: callback_function} para o parâmetro hooks do método de requisição:

hooks=dict(response=print_url)

A callback_function irá receber um bloco de dado como seu primeiro argumento.

def print_url(r):
    print(r.url)

Se ocorrer um erro durante a execução do seu callback, é dado um warning.

Se a função de callback retorna um valor, assume-se que este substitui os dados que foram passados. Se a função não retorna nada, nada mais é afetado.

Vamos imprimir alguns argumentos do método de requisição em tempo de execução:

>>> requests.get('http://httpbin.org', hooks=dict(response=print_url))
http://httpbin.org
<Response [200]>

Autenticação personalizada¶

Requests permite que você especifique seu próprio mecanismo de autenticação.

Todo objeto executável que é passado como argumento auth para um método de requisição terá a oportunidade de modificar a requisição antes que ela seja enviada.

Implementações de autenticação são subclasses de requests.auth.AuthBase, e são fáceis de se definir. Requests fornece duas implementações comuns de esquemas de autenticação em requests.auth: HTTPBasicAuth e HTTPDigestAuth.

Vamos supor que temos um serviço web que irá somente responder se o cabeçalho X-Pizza for definido para um valor de senha. Improvável, mas vamos continuar assim.

from requests.auth import AuthBase

class PizzaAuth(AuthBase):
    """Inclui autenticação HTTP Pizza para o dado objeto Request."""
    def __init__(self, username):
        # configura qualquer dado relacionado a autenticação aqui
        self.username = username

    def __call__(self, r):
        # modifica e retorna a requisição
        r.headers['X-Pizza'] = self.username
        return r

Então, nós podemos fazer uma requisição utilizando a nossa autenticação Pizza:

>>> requests.get('http://pizzabin.org/admin', auth=PizzaAuth('kenneth'))
<Response [200]>

Requisições de Streaming¶

Com requests.Response.iter_lines() você pode facilmente iterar por APIs de streaming como a API de Streaming do Twitter.

Para usar API de Streaming do Twitter para monitorar a palavra “requests”:

import json
import requests

r = requests.post('http://httpbin.org/stream/20', stream=True)

for line in r.iter_lines():

    # filtrar novas linhas de keep-alive
    if line:
        print json.loads(line)

Proxies¶

Se você precisar um proxy, você pode configurar requisições individuais com o argumento proxies de qualquer método de requisição:

import requests

proxies = {
  "http": "http://10.10.1.10:3128",
  "https": "http://10.10.1.10:1080",
}

requests.get("http://example.org", proxies=proxies)

Você também pode configurar proxies com as variáveis de ambiente HTTP_PROXY e HTTPS_PROXY.

$ export HTTP_PROXY="http://10.10.1.10:3128"
$ export HTTPS_PROXY="http://10.10.1.10:1080"
$ python
>>> import requests
>>> requests.get("http://example.org")

Para usar autenticação básica HTTP com seu proxy, use a síntaxe http://user:password@host/:

proxies = {
    "http": "http://user:pass@10.10.1.10:3128/",
}

Concordância¶

Requests tem intenção de estar de acordo com todas as especificações relevantes e RFCs onde está concordância não causar dificuldades para os usuários. Esta atenção para a especificação pode levar a alguns comportamentos que podem parecer incomuns para aqueles não familiarizados com a especificação relevante.

Codificações¶

Quando você recebe uma resposta, Requests tenta adivinhar a codificação a ser usada quando decodificar a resposta quando você chamar o método Response.text. Requests irá primeiro checar por uma codificação nos cabeçalhos HTTP, e se não houver nenhuma presente, irá usar charade para tentar adivinhar a codificação.

A única vez que Requests não fará isso é nenhum conjunto de caracteres explícito estiver presente nos cabeçalhos HTTP e o cabeçalho Content-Type contiver text. Nesta situação, a RFC 2616 especifica que o conjunto de caracteres padrão deve ser ISO-8859-1. Requests segue a especificação neste caso. Se você precisa de uma codficação diferente, você pode definir manualmente a propriedade Response.encoding ou usar a resposta crua com Response.content.

Verbos HTTP¶

Requests fornece acesso para praticamente todos os verbos HTTP: GET, OPTIONS, HEAD, POST, PUT, PATCH e DELETE. A seguir encontram-se exemplos detalhados de como usar estes vários verbos em Requests, usando a API do GitHub.

Nós começaremos com o verbo mais comumente usado: GET. HTTP GET é um método idempotente que retorna um recurso de uma URL dada. Como resultado, é o verbo que você deve usar quando tentar buscar dados de um local na web. Um exemplo de uso seria tentar pegar informações sobre um commit específico go GitHub. Supondo que queremos ver o commit a050af de Requests. Nós faríamos de tal forma:

>>> import requests
>>> r = requests.get('https://api.github.com/repos/kennethreitz/requests/git/commits/a050faf084662f3a352dd1a941f2c7c9f886d4ad')

Nós devemos confirmar que o GitHub respondeu corretamente. Se respondeu, nós queremos verificar o tipo de conteúdo respondido. Fazendo da seguinte forma:

>>> if (r.status_code == requests.codes.ok):
...     print r.headers['content-type']
...
application/json; charset=utf-8

Então, GitHub retorna JSON. Isto é ótimo, nós podemos usar o método r.json para intepretá-lo como objetos Python.

>>> commit_data = r.json()
>>> print commit_data.keys()
[u'committer', u'author', u'url', u'tree', u'sha', u'parents', u'message']
>>> print commit_data[u'committer']
{u'date': u'2012-05-10T11:10:50-07:00', u'email': u'me@kennethreitz.com', u'name': u'Kenneth Reitz'}
>>> print commit_data[u'message']
makin' history

Por enquanto, tudo simples. Bem, vamos investigar um pouco a API do GitHub. Agora, poderíamos olhar a documentação, mas nós vamos nos divertir um pouco mais usando Requests. Nós podemos tirar proveito do verbo OPTIONS do Requests para ver que tipos de métodos HTTP são suportados pelo verbo na URL que acabamos de usar.

>>> verbs = requests.options(r.url)
>>> verbs.status_code
500

Hein, o que? Isso não ajuda nada! Aparentemente, GitHub, como muitos outras APIs, não implementam de fato o método OPTIONS. Isso é um descuido que incomoda, mas tudo bem, nós podemos simplesmente usar a documentação chata. Se o GitHub tivesse implementado OPTIONS corretamente, eles deverião retornar os métodos permitidos nos cabeçalhos, por exemplo

>>> verbs = requests.options('http://a-good-website.com/api/cats')
>>> print verbs.headers['allow']
GET,HEAD,POST,OPTIONS

Observando a documentação, nós podemos ver que o único método permitido para commits é POST, que cria um novo commit. Como nós estamos o repositório do Requests, nós provavelmente deveríamos evitar fazer POSTS descuidados nele. Ao invés disso, vamos brincar com a funcionalidade de Issues do GitHub.

Essa documentação foi adicionada em resposta a Issue #482. Dado que esta issue já existe, nós a usaremos como exemplo. Começaremos buscando-a.

>>> r = requests.get('https://api.github.com/repos/kennethreitz/requests/issues/482')
>>> r.status_code
200
>>> issue = json.loads(r.text)
>>> print issue[u'title']
Feature any http verb in docs
>>> print issue[u'comments']
3

Legal, temos 3 comentários. Vamos dar uma olhada no último deles.

>>> r = requests.get(r.url + u'/comments')
>>> r.status_code
200
>>> comments = r.json()
>>> print comments[0].keys()
[u'body', u'url', u'created_at', u'updated_at', u'user', u'id']
>>> print comments[2][u'body']
Probably in the "advanced" section

Bem, esse comentário é meio bobo. Vamos postar um comentário contando ao autor que ele é bobo. Quem é o autor, mesmo?

>>> print comments[2][u'user'][u'login']
kennethreitz

Tudo bem, então falaremos para esse tal Kenneth que achamos que esse exemplo deveria aparecer no guia de início rápido. De acordo com a documentação da API do GitHub, o jeito de fazer isso é fazer um POST no tópico. Faremos isto.

>>> body = json.dumps({u"body": u"Sounds great! I'll get right on it!"})
>>> url = u"https://api.github.com/repos/kennethreitz/requests/issues/482/comments"
>>> r = requests.post(url=url, data=body)
>>> r.status_code
404

Hm, isso é estranho. Provavelmente precisamos nos autenticar. Isso vai ser chato, né? Errado. Requests deixa simples o uso de várias formas de autenticação, incluindo a bastante comum Basic Auth.

>>> from requests.auth import HTTPBasicAuth
>>> auth = HTTPBasicAuth('fake@example.com', 'not_a_real_password')
>>> r = requests.post(url=url, data=body, auth=auth)
>>> r.status_code
201
>>> content = r.json()
>>> print content[u'body']
Sounds great! I'll get right on it.

Brilhanete. Mas, espere, não! Eu queria adicionar que eu demoraria um pouco, porque eu tinha que alimentar meu gato. Se pelo menos eu pudesse editar esse comentário! Ainda bem que o GitHub nos permite usar outro verbo HTTP, PATCH, para editar esse comentário. Vamos fazer isso.

>>> print content[u"id"]
5804413
>>> body = json.dumps({u"body": u"Sounds great! I'll get right on it once I feed my cat."})
>>> url = u"https://api.github.com/repos/kennethreitz/requests/issues/comments/5804413"
>>> r = requests.patch(url=url, data=body, auth=auth)
>>> r.status_code
200

Excelente. Agora, apenas para torturar esse tal Kenneth, eu decidi que vou fazer ele suar e não vou contar que estou trabalhando nisso. Isso significa que eu quero apagar esse comentário. GitHub nos deixa apagar comentários usando o método incrível, e de nome adequado, DELETE. Vamos nos livrar do comentário.

>>> r = requests.delete(url=url, auth=auth)
>>> r.status_code
204
>>> r.headers['status']
'204 No Content'

Excelente. Apagado. Agora a última que eu quero saber o quanto do meu limite eu já usei. Vamos descobrir. GitHub envia essa informação nos cabeçalhos, então, ao invé de baixar toda a página, enviarei uma requisição HEAD para pegar os cabeçalhos.

>>> r = requests.head(url=url, auth=auth)
>>> print r.headers
...
'x-ratelimit-remaining': '4995'
'x-ratelimit-limit': '5000'
...

Excelente. Agora, devemos escrever um programa Python que abusa a API do GitHub de vários jeitos legais, mais 4995 vezes.

Cabeçalhos Link¶

Várias APIs HTTP fornecem cabeçalhos Link. Eles deixam as APIs mais descritiva e facilmente descoberta.

GitHub os usa para paginação na sua API, por exemplo:

>>> url = 'https://api.github.com/users/kennethreitz/repos?page=1&per_page=10'
>>> r = requests.head(url=url)
>>> r.headers['link']
'<https://api.github.com/users/kennethreitz/repos?page=2&per_page=10>; rel="next", <https://api.github.com/users/kennethreitz/repos?page=6&per_page=10>; rel="last"'

Requests irá automaticamente interpretar esses cabeçalhos de link e os fará facilmente consumíveis:

>>> r.links["next"]
{'url': 'https://api.github.com/users/kennethreitz/repos?page=2&per_page=10', 'rel': 'next'}

>>> r.links["last"]
{'url': 'https://api.github.com/users/kennethreitz/repos?page=7&per_page=10', 'rel': 'last'}

Transport Adapters¶

A partir da versão v1.0.0, Requests mudou para um design interno modular. Parte do motivo que isso foi feito era pra implementar Transport Adapters, originalmente descrito aqui. Transport Adapters fornecem um mecanismo para definir métodos de interação para um serviço HTTP. Em particular, eles permitem que você aplique configurações por serviço.

Requests é lançado com um único Transport Adapter, o HTTPAdapter. Este adaptador fornece a interação padrão do Requests com HTTp e HTTPS usando a poderosa biblioteca urllib3. Sempre que uma Session de Requests é inicializada, um desses é anexado ao objeto Session para HTTP e outro para HTTPS.

Requests habilita que usuários criem e usem seus próprios Transport Adapters que fornecam funcionalidades específicas. Uma vez criado, um Transport Adapter pode ser incluído em um objeto Session, junto com uma indicação de quais serviços web ele deve ser aplicado.

>>> s = requests.Session()
>>> s.mount('http://www.github.com', MyAdapter())

A chamada mount registra uma instância específica a um prefixo. Uma vez incluso, qualquer requisição HTTP usando a sessão cuja URL começa com o dado prefixo usará o Transport Adapter dado.

Implementando um Transport Adapter está além do escopo desta documentação, mas um bom começo seria herdar a classe requests.adapters.BaseAdapter.

Autenticação¶

Este documento discute o uso de vários tipos de autenticação com Requests.

Muitos serviços web exigem autenticação, e existem vários tipos diferentes. Abaixo, vamos esboçar várias formas de autenticação disponíveis no Requests, do simples ao complexo.

HTTP Basic Auth¶

Muitos serviços web que exigem autenticação aceitam HTTP Basic Auth. Esta é a maneira mais simples e Requests suporta-a nativamente.

Fazer requisições usando HTTP Basic Auth é muito simples:

>>> from requests.auth import HTTPBasicAuth
>>> requests.get('https://api.github.com/user', auth=HTTPBasicAuth('user', 'pass'))
<Response [200]>

Na verdade, HTTP Basic Auth é tão comum que Requests fornece um atalho útil para usá-lo:

>>> requests.get('https://api.github.com/user', auth=('user', 'pass'))
<Response [200]>

Fornecendo as credenciais em uma tupla desse jeito é exatamente o mesmo que usar HTTPBasicAuth como no exemplo acima.

Autenticação Digest¶

Outra forma bastante popular de autenticação HTTP é autenticação Digest, e Requests também a suporta nativamente:

>>> from requests.auth import HTTPDigestAuth
>>> url = 'http://httpbin.org/digest-auth/auth/user/pass'
>>> requests.get(url, auth=HTTPDigestAuth('user', 'pass'))
<Response [200]>

Autenticação com OAuth 1¶

Uma forma comum de autenticação para várias APIs web é OAuth. A biblioteca requests-oauthlib permite que usuários do Requests façam requisições autenticadas facilmente:

>>> import request
>>> from requests_oauthlib import OAuth1

>>> url = 'https://api.twitter.com/1.1/account/verify_credentials.json'
>>> auth = OAuth1('YOUR_APP_KEY', 'YOUR_APP_SECRET',
                  'USER_OAUTH_TOKEN', 'USER_OAUTH_TOKEN_SECRET')

>>> requests.get(url, auth=auth)
<Response [200]>

Para mais informações sobre como o fluxo do OAuth funciona, veja o site official do OAuth. Para exemplo e documentação do requests-oauthlib, veja o repositório do requests_oauthlib no GitHub.

Outras formas de autenticação¶

Requests é feito para permitir que outras formas de autenticação sejam fácil e rapidamente plugadas. Membros da comunidade open-source frequentemente escrevem handlers para formas de autenticação mais complicadas ou menos comumente usadas. Algumas das melhores foram reunidas sob a organização Requests, incluindo:

Se você quiser usar algumas dessas formas de autenticação, vá direto para a página delas no GitHub e siga as instruções.

Novas formas de autenticação¶

Se você não conseguir achar uma boa implementação para a forma de autenticação que quiser, você mesmo pode implementá-la. Requests deixa fácil a adição da sua própria forma de autenticação.

Para fazer isto, herde a classe requests.auth.AuthBase e implemente o método __call__(). Quando um handler de autenticação é anexada a uma requisição, ele é chamado durante a configuração da requisição. O método __call__() deve, então, fazer o que tiver que ser feito para fazer a autenticação funcionar. Algumas formas de autenticação poderão adicionar hooks para fornecer alguma funcionalidade posterior.

Exemplos podem ser encontrados na organização Requests e no arquivo auth.py.

Guia da Comunidade¶

Esta parte da documentação, que é principalmente prosa, detalha o ecossistema e a comunidade do Requests.

FAQ¶

Esta parte da documentação responde as perguntas mais frequentes sobre Requests.

Dados codificados?¶

Requests descomprime automaticamente as respostas comprimidas com gzip e faz o possível para decodificar o conteúdo para unicode quando possível.

Você tem acesso direto à resposta crua (e até mesmo ao socket), se for necessário.

User-Agents personalizados?¶

Requests permite que você facilmente sobrescreva informações de User-Agent, além de qualquer outro cabeçalho HTTP.

Por que não Httplib2?¶

Chris Adams deu uma excelente explicação em Hacker News:

httplib2 é parte do motivo por que você deveria usar requests: é bem mais respeitável como um cliente, mas não é tão bem documentado e ainda precisa de muito código para relizar operações básicas. Eu reconheço o que httplib2 está tentando fazer, no sentido que há muitas complicações de baixo nível em construir um cliente HTTP moderno, porém, use requests. Kenneth Reitz é bastante motivado e ele entende o conceito de que coisas simples devem ser simples enquanto httplib2 parece muito mais um exercício acadêmico do que algo que as pessoas deveriam usar para criar sistemas em produção[1].

Confissão: Eu apareço no arquivo AUTHORS do requests mas eu só tomo crédito por mais ou menos 0,0001% do quão sensacional ele é.

1. http://code.google.com/p/httplib2/issues/detail?id=96 é um bom exemplo: um bug que afeta muitas pessoas, havia uma correção disponível há meses, que funcionava muito bem quando eu o aplicava em um fork e passava TBs de dados por ele, mas demorou mais de 1 ano para ser aplicado ao código e ainda mais tempo para estar disponível pelo PyPI, onde qualquer outro projeto que depende de “httplib2” conseguiria a versão funcional.

Suporte ao Python 3?¶

Sim! Aqui está uma lista de plataformas do Python que são suportadas oficialmente:

Python 2.6
Python 2.7
Python 3.1
Python 3.2
Python 3.3
PyPy 1.9

Integrações¶

ScraperWiki¶

ScraperWiki é um excelente serviço que permite você rodar scripts Python, Ruby e PHP de scrapers na web. Agora, Requests v0.6.1 está disponível para você usar nos seus scrapers.

Para testar, simplesmente use:

import requests

Python para iOS¶

Requests está incluso no maravilhoso Python para iOS!

Para testar, simplesmente use:

import requests

Artigos e Palestras¶

Python para a Web ensina como usar Python para interagir com a web, usando Requests.
Resenha do Requests por Daniel Greenfields
Minha palestra ‘Python para Humanos’ ( audio )
Palestra do Issac Kelly ‘Consumindo APIs Web’
Post em um blog sobre Requests via Yum
Post em um blog russo introduzindo Requests
Post em um blog francês introduzindo Requests

Suporte¶

Se você tiver perguntas ou encontrar problemas com Requests, existem várias opções:

Envie um Tweet¶

Se a sua pergunta tiver menos de 140 caracteres, fique à vontade para mandar um tweet para @kennethreitz.

Criar uma Issue¶

Se você notar algum comportamento inexperado com Requests, ou você quiser suporte para alguma nova funcionalidade, crie uma issue no GitHub.

E-mail¶

Eu ficarei bastante feliz de responder qualquer pergunta pessoal ou profunda sobre Requests. Sinta-se à vontade para enviar um e-mail para requests@kennethreitz.com.

IRC¶

O canal oficial do Requests no Freenode é #python-requests

Eu também estou disponível kennethreitz no Freenode.

Atualizações¶

Se você quiser ficar atualizado com a comunidade e com o desenvolvimento de Requests, existem várias opções:

GitHub¶

A melhor maneira de acompanhar o desenvolvimento de Requests é pelo repositório do GitHub.

Twitter¶

Eu frequentemente posto tweets sobre novas funcionalidades e lançamentos de requests.

Siga @kennethreitz para notícias.

Lista de e-mails¶

Existe uma lista de e-mails com pequeno fluxo de e-mails para Requests. Para se inscrever na lista, mande um e-mail para requests@librelist.org.

Documentação da API¶

Se você estiver procurando por informações sobre uma função, classe ou método específico, esta parte da documentação é para você.

Interface de Desenvolvedor¶

Esta parte da documentação cobre todas as interfaces do Requests. Para partes onde Requests depende de bibliotecas externas, nós documentamos o mais imoprtante aqui e fornecemos links para a documentação oficial.

Interface principal¶

Todas as funcionalidades de Requests podem ser acessadas por estes 7 métodos. Todos retornam uma instância de Response.

requests.request(method, url, **kwargs)¶

Constructs and sends a Request. Returns Response object.

Parâmetros:

method – method for the new Request object.
url – URL for the new Request object.
params – (optional) Dictionary or bytes to be sent in the query string for the Request.
data – (optional) Dictionary, bytes, or file-like object to send in the body of the Request.
headers – (optional) Dictionary of HTTP Headers to send with the Request.
cookies – (optional) Dict or CookieJar object to send with the Request.
files – (optional) Dictionary of ‘name’: file-like-objects (or {‘name’: (‘filename’, fileobj)}) for multipart encoding upload.
auth – (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth.
timeout – (optional) Float describing the timeout of the request.
allow_redirects – (optional) Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
verify – (optional) if True, the SSL cert will be verified. A CA_BUNDLE path can also be provided.
stream – (optional) if False, the response content will be immediately downloaded.
cert – (optional) if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.

Usage:

>>> import requests
>>> req = requests.request('GET', 'http://httpbin.org/get')
<Response [200]>

requests.head(url, **kwargs)¶

Sends a HEAD request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

requests.get(url, **kwargs)¶

Sends a GET request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

requests.post(url, data=None, **kwargs)¶

Sends a POST request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. data – (optional) Dictionary, bytes, or file-like object to send in the body of the `Request`. **kwargs – Optional arguments that `request` takes.

requests.put(url, data=None, **kwargs)¶

Sends a PUT request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. data – (optional) Dictionary, bytes, or file-like object to send in the body of the `Request`. **kwargs – Optional arguments that `request` takes.

requests.patch(url, data=None, **kwargs)¶

Sends a PATCH request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. data – (optional) Dictionary, bytes, or file-like object to send in the body of the `Request`. **kwargs – Optional arguments that `request` takes.

requests.delete(url, **kwargs)¶

Sends a DELETE request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

Classes baixo-nível¶

class requests.Request(method=None, url=None, headers=None, files=None, data={}, params={}, auth=None, cookies=None, hooks=None)¶

A user-created Request object.

Used to prepare a PreparedRequest, which is sent to the server.

Parâmetros:

method – HTTP method to use.
url – URL to send.
headers – dictionary of headers to send.
files – dictionary of {filename: fileobject} files to multipart upload.
data – the body to attach the request. If a dictionary is provided, form-encoding will take place.
params – dictionary of URL parameters to append to the URL.
auth – Auth handler or (user, pass) tuple.
cookies – dictionary or CookieJar of cookies to attach to this request.
hooks – dictionary of callback hooks, for internal usage.

Usage:

>>> import requests
>>> req = requests.Request('GET', 'http://httpbin.org/get')
>>> req.prepare()
<PreparedRequest [GET]>

deregister_hook(event, hook)¶: Deregister a previously registered hook. Returns True if the hook existed, False if not.

prepare()¶: Constructs a PreparedRequest for transmission and returns it.

register_hook(event, hook)¶: Properly register a hook.

class requests.Response¶

The Response object, which contains a server’s response to an HTTP request.

apparent_encoding¶: The apparent encoding, provided by the lovely Charade library (Thanks, Ian!).

content¶: Content of the response, in bytes.

cookies = None¶: A CookieJar of Cookies the server sent back.

elapsed = None¶: The amount of time elapsed between sending the request and the arrival of the response (as a timedelta)

encoding = None¶: Encoding to decode with when accessing r.text.

headers = None¶: Case-insensitive Dictionary of Response Headers. For example, headers['content-encoding'] will return the value of a 'Content-Encoding' response header.

history = None¶: A list of Response objects from the history of the Request. Any redirect responses will end up here. The list is sorted from the oldest to the most recent request.

iter_content(chunk_size=1, decode_unicode=False)¶: Iterates over the response data. When stream=True is set on the request, this avoids reading the content at once into memory for large responses. The chunk size is the number of bytes it should read into memory. This is not necessarily the length of each item returned as decoding can take place.

iter_lines(chunk_size=512, decode_unicode=None)¶: Iterates over the response data, one line at a time. When stream=True is set on the request, this avoids reading the content at once into memory for large responses.

json(**kwargs)¶

Returns the json-encoded content of a response, if any.

Parâmetros:	**kwargs – Optional arguments that `json.loads` takes.

links¶: Returns the parsed header links of the response, if any.

raise_for_status()¶: Raises stored HTTPError, if one occurred.

raw = None¶: File-like object representation of response (for advanced usage). Requires that ``stream=True` on the request.

status_code = None¶: Integer Code of responded HTTP Status.

text¶

Content of the response, in unicode.

if Response.encoding is None and chardet module is available, encoding will be guessed.

url = None¶: Final URL location of Response.

Sessões de requisição¶

class requests.Session¶

A Requests session.

Provides cookie persistience, connection-pooling, and configuration.

Basic Usage:

>>> import requests
>>> s = requests.Session()
>>> s.get('http://httpbin.org/get')
200

auth = None¶: Default Authentication tuple or object to attach to Request.

cert = None¶: SSL certificate default.

close()¶: Closes all adapters and as such the session

delete(url, **kwargs)¶

Sends a DELETE request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

get(url, **kwargs)¶

Sends a GET request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

get_adapter(url)¶: Returns the appropriate connnection adapter for the given URL.

head(url, **kwargs)¶

Sends a HEAD request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

headers = None¶: A case-insensitive dictionary of headers to be sent on each Request sent from this Session.

hooks = None¶: Event-handling hooks.

max_redirects = None¶: Maximum number of redirects to follow.

mount(prefix, adapter)¶: Registers a connection adapter to a prefix.

options(url, **kwargs)¶

Sends a OPTIONS request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

params = None¶: Dictionary of querystring data to attach to each Request. The dictionary values may be lists for representing multivalued query parameters.

patch(url, data=None, **kwargs)¶

Sends a PATCH request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. data – (optional) Dictionary, bytes, or file-like object to send in the body of the `Request`. **kwargs – Optional arguments that `request` takes.

post(url, data=None, **kwargs)¶

Sends a POST request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. data – (optional) Dictionary, bytes, or file-like object to send in the body of the `Request`. **kwargs – Optional arguments that `request` takes.

proxies = None¶: Dictionary mapping protocol to the URL of the proxy (e.g. {‘http’: ‘foo.bar:3128’}) to be used on each Request.

put(url, data=None, **kwargs)¶

Sends a PUT request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. data – (optional) Dictionary, bytes, or file-like object to send in the body of the `Request`. **kwargs – Optional arguments that `request` takes.

request(method, url, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None)¶

Constructs a Request, prepares it and sends it. Returns Response object.

Parâmetros:

method – method for the new Request object.
url – URL for the new Request object.
params – (optional) Dictionary or bytes to be sent in the query string for the Request.
data – (optional) Dictionary or bytes to send in the body of the Request.
headers – (optional) Dictionary of HTTP Headers to send with the Request.
cookies – (optional) Dict or CookieJar object to send with the Request.
files – (optional) Dictionary of ‘filename’: file-like-objects for multipart encoding upload.
auth – (optional) Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.
timeout – (optional) Float describing the timeout of the request.
allow_redirects – (optional) Boolean. Set to True by default.
proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
stream – (optional) whether to immediately download the response content. Defaults to False.
verify – (optional) if True, the SSL cert will be verified. A CA_BUNDLE path can also be provided.
cert – (optional) if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.

resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None)¶: Receives a Response. Returns a generator of Responses.

send(request, **kwargs)¶: Send a given PreparedRequest.

stream = None¶: Stream response content default.

trust_env = None¶: Should we trust the environment?

verify = None¶: SSL Verification default.

class requests.adapters.HTTPAdapter(pool_connections=10, pool_maxsize=10, max_retries=0)¶

The built-in HTTP Adapter for urllib3.

Provides a general-case interface for Requests sessions to contact HTTP and HTTPS urls by implementing the Transport Adapter interface. This class will usually be created by the Session class under the covers.

Parâmetros:	pool_connections – The number of urllib3 connection pools to cache. pool_maxsize – The maximum number of connections to save in the pool. max_retries – The maximum number of retries each connection should attempt.

Usage:

>>> import requests
>>> s = requests.Session()
>>> a = requests.adapters.HTTPAdapter()
>>> s.mount('http://', a)

add_headers(request, **kwargs)¶

Add any headers needed by the connection. Currently this adds a Proxy-Authorization header.

This should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parâmetros:	request – The `PreparedRequest` to add headers to. kwargs – The keyword arguments from the call to send().

build_response(req, resp)¶

Builds a Response object from a urllib3 response. This should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter

Parâmetros:	req – The `PreparedRequest` used to generate the response. resp – The urllib3 response object.

cert_verify(conn, url, verify, cert)¶

Verify a SSL certificate. This method should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parâmetros:	conn – The urllib3 connection object associated with the cert. url – The requested URL. verify – Whether we should actually verify the certificate. cert – The SSL certificate to verify.

close()¶

Disposes of any internal state.

Currently, this just closes the PoolManager, which closes pooled connections.

get_connection(url, proxies=None)¶

Returns a urllib3 connection for the given URL. This should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parâmetros:	url – The URL to connect to. proxies – (optional) A Requests-style dictionary of proxies used on this request.

init_poolmanager(connections, maxsize)¶

Initializes a urllib3 PoolManager. This method should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parâmetros:	connections – The number of urllib3 connection pools to cache. maxsize – The maximum number of connections to save in the pool.

request_url(request, proxies)¶

Obtain the url to use when making the final request.

If the message is being sent through a proxy, the full URL has to be used. Otherwise, we should only use the path portion of the URL.

This shoudl not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parâmetros:	request – The `PreparedRequest` being sent. proxies – A dictionary of schemes to proxy URLs.

send(request, stream=False, timeout=None, verify=True, cert=None, proxies=None)¶

Sends PreparedRequest object. Returns Response object.

Parâmetros:	request – The `PreparedRequest` being sent. stream – (optional) Whether to stream the request content. timeout – (optional) The timeout on the request. verify – (optional) Whether to verify SSL certificates. vert – (optional) Any user-provided SSL certificate to be trusted. proxies – (optional) The proxies dictionary to apply to the request.

Exceções¶

exception requests.RequestException¶: There was an ambiguous exception that occurred while handling your request.

exception requests.ConnectionError¶: A Connection error occurred.

exception requests.HTTPError(*args, **kwargs)¶: An HTTP error occurred.

exception requests.URLRequired¶: A valid URL is required to make a request.

exception requests.TooManyRedirects¶: Too many redirects.

Referência de código de status¶

requests.codes()¶: Dictionary lookup object.

>>> requests.codes['temporary_redirect']
307

>>> requests.codes.teapot
418

>>> requests.codes['\o/']
200

Cookies¶

Codificações¶

Classes¶

class requests.Response

The Response object, which contains a server’s response to an HTTP request.

apparent_encoding: The apparent encoding, provided by the lovely Charade library (Thanks, Ian!).

content: Content of the response, in bytes.

cookies = None: A CookieJar of Cookies the server sent back.

elapsed = None: The amount of time elapsed between sending the request and the arrival of the response (as a timedelta)

encoding = None: Encoding to decode with when accessing r.text.

headers = None: Case-insensitive Dictionary of Response Headers. For example, headers['content-encoding'] will return the value of a 'Content-Encoding' response header.

history = None: A list of Response objects from the history of the Request. Any redirect responses will end up here. The list is sorted from the oldest to the most recent request.

iter_content(chunk_size=1, decode_unicode=False): Iterates over the response data. When stream=True is set on the request, this avoids reading the content at once into memory for large responses. The chunk size is the number of bytes it should read into memory. This is not necessarily the length of each item returned as decoding can take place.

iter_lines(chunk_size=512, decode_unicode=None): Iterates over the response data, one line at a time. When stream=True is set on the request, this avoids reading the content at once into memory for large responses.

json(**kwargs)

Returns the json-encoded content of a response, if any.

Parâmetros:	**kwargs – Optional arguments that `json.loads` takes.

links: Returns the parsed header links of the response, if any.

raise_for_status(): Raises stored HTTPError, if one occurred.

raw = None: File-like object representation of response (for advanced usage). Requires that ``stream=True` on the request.

status_code = None: Integer Code of responded HTTP Status.

text

Content of the response, in unicode.

if Response.encoding is None and chardet module is available, encoding will be guessed.

url = None: Final URL location of Response.

class requests.Request(method=None, url=None, headers=None, files=None, data={}, params={}, auth=None, cookies=None, hooks=None)

A user-created Request object.

Used to prepare a PreparedRequest, which is sent to the server.

Parâmetros:

method – HTTP method to use.
url – URL to send.
headers – dictionary of headers to send.
files – dictionary of {filename: fileobject} files to multipart upload.
data – the body to attach the request. If a dictionary is provided, form-encoding will take place.
params – dictionary of URL parameters to append to the URL.
auth – Auth handler or (user, pass) tuple.
cookies – dictionary or CookieJar of cookies to attach to this request.
hooks – dictionary of callback hooks, for internal usage.

Usage:

>>> import requests
>>> req = requests.Request('GET', 'http://httpbin.org/get')
>>> req.prepare()
<PreparedRequest [GET]>

deregister_hook(event, hook): Deregister a previously registered hook. Returns True if the hook existed, False if not.

prepare(): Constructs a PreparedRequest for transmission and returns it.

register_hook(event, hook): Properly register a hook.

class requests.PreparedRequest¶

The fully mutable PreparedRequest object, containing the exact bytes that will be sent to the server.

Generated from either a Request object or manually.

Usage:

>>> import requests
>>> req = requests.Request('GET', 'http://httpbin.org/get')
>>> r = req.prepare()
<PreparedRequest [GET]>

>>> s = requests.Session()
>>> s.send(r)
<Response [200]>

body = None¶: request body to send to the server.

deregister_hook(event, hook)¶: Deregister a previously registered hook. Returns True if the hook existed, False if not.

headers = None¶: dictionary of HTTP headers.

hooks = None¶: dictionary of callback hooks, for internal usage.

method = None¶: HTTP verb to send to the server.

path_url¶: Build the path URL to use.

prepare_auth(auth, url='')¶: Prepares the given HTTP auth data.

prepare_body(data, files)¶: Prepares the given HTTP body data.

prepare_cookies(cookies)¶: Prepares the given HTTP cookie data.

prepare_headers(headers)¶: Prepares the given HTTP headers.

prepare_hooks(hooks)¶: Prepares the given hooks.

prepare_method(method)¶: Prepares the given HTTP method.

prepare_url(url, params)¶: Prepares the given HTTP URL.

register_hook(event, hook)¶: Properly register a hook.

url = None¶: HTTP URL to send the request to.

class requests.Session

A Requests session.

Provides cookie persistience, connection-pooling, and configuration.

Basic Usage:

>>> import requests
>>> s = requests.Session()
>>> s.get('http://httpbin.org/get')
200

auth = None: Default Authentication tuple or object to attach to Request.

cert = None: SSL certificate default.

close(): Closes all adapters and as such the session

delete(url, **kwargs)

Sends a DELETE request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

get(url, **kwargs)

Sends a GET request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

get_adapter(url): Returns the appropriate connnection adapter for the given URL.

head(url, **kwargs)

Sends a HEAD request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

headers = None: A case-insensitive dictionary of headers to be sent on each Request sent from this Session.

hooks = None: Event-handling hooks.

max_redirects = None: Maximum number of redirects to follow.

mount(prefix, adapter): Registers a connection adapter to a prefix.

options(url, **kwargs)

Sends a OPTIONS request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. **kwargs – Optional arguments that `request` takes.

params = None: Dictionary of querystring data to attach to each Request. The dictionary values may be lists for representing multivalued query parameters.

patch(url, data=None, **kwargs)

Sends a PATCH request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. data – (optional) Dictionary, bytes, or file-like object to send in the body of the `Request`. **kwargs – Optional arguments that `request` takes.

post(url, data=None, **kwargs)

Sends a POST request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. data – (optional) Dictionary, bytes, or file-like object to send in the body of the `Request`. **kwargs – Optional arguments that `request` takes.

proxies = None: Dictionary mapping protocol to the URL of the proxy (e.g. {‘http’: ‘foo.bar:3128’}) to be used on each Request.

put(url, data=None, **kwargs)

Sends a PUT request. Returns Response object.

Parâmetros:	url – URL for the new `Request` object. data – (optional) Dictionary, bytes, or file-like object to send in the body of the `Request`. **kwargs – Optional arguments that `request` takes.

request(method, url, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None)

Constructs a Request, prepares it and sends it. Returns Response object.

Parâmetros:

method – method for the new Request object.
url – URL for the new Request object.
params – (optional) Dictionary or bytes to be sent in the query string for the Request.
data – (optional) Dictionary or bytes to send in the body of the Request.
headers – (optional) Dictionary of HTTP Headers to send with the Request.
cookies – (optional) Dict or CookieJar object to send with the Request.
files – (optional) Dictionary of ‘filename’: file-like-objects for multipart encoding upload.
auth – (optional) Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.
timeout – (optional) Float describing the timeout of the request.
allow_redirects – (optional) Boolean. Set to True by default.
proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
stream – (optional) whether to immediately download the response content. Defaults to False.
verify – (optional) if True, the SSL cert will be verified. A CA_BUNDLE path can also be provided.
cert – (optional) if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.

resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None): Receives a Response. Returns a generator of Responses.

send(request, **kwargs): Send a given PreparedRequest.

stream = None: Stream response content default.

trust_env = None: Should we trust the environment?

verify = None: SSL Verification default.

class requests.adapters.HTTPAdapter(pool_connections=10, pool_maxsize=10, max_retries=0)

The built-in HTTP Adapter for urllib3.

Provides a general-case interface for Requests sessions to contact HTTP and HTTPS urls by implementing the Transport Adapter interface. This class will usually be created by the Session class under the covers.

Parâmetros:	pool_connections – The number of urllib3 connection pools to cache. pool_maxsize – The maximum number of connections to save in the pool. max_retries – The maximum number of retries each connection should attempt.

Usage:

>>> import requests
>>> s = requests.Session()
>>> a = requests.adapters.HTTPAdapter()
>>> s.mount('http://', a)

add_headers(request, **kwargs)

Add any headers needed by the connection. Currently this adds a Proxy-Authorization header.

This should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parâmetros:	request – The `PreparedRequest` to add headers to. kwargs – The keyword arguments from the call to send().

build_response(req, resp)

Builds a Response object from a urllib3 response. This should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter

Parâmetros:	req – The `PreparedRequest` used to generate the response. resp – The urllib3 response object.

cert_verify(conn, url, verify, cert)

Verify a SSL certificate. This method should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parâmetros:	conn – The urllib3 connection object associated with the cert. url – The requested URL. verify – Whether we should actually verify the certificate. cert – The SSL certificate to verify.

close()

Disposes of any internal state.

Currently, this just closes the PoolManager, which closes pooled connections.

get_connection(url, proxies=None)

Returns a urllib3 connection for the given URL. This should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parâmetros:	url – The URL to connect to. proxies – (optional) A Requests-style dictionary of proxies used on this request.

init_poolmanager(connections, maxsize)

Initializes a urllib3 PoolManager. This method should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parâmetros:	connections – The number of urllib3 connection pools to cache. maxsize – The maximum number of connections to save in the pool.

request_url(request, proxies)

Obtain the url to use when making the final request.

If the message is being sent through a proxy, the full URL has to be used. Otherwise, we should only use the path portion of the URL.

This shoudl not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parâmetros:	request – The `PreparedRequest` being sent. proxies – A dictionary of schemes to proxy URLs.

send(request, stream=False, timeout=None, verify=True, cert=None, proxies=None)

Sends PreparedRequest object. Returns Response object.

Parâmetros:	request – The `PreparedRequest` being sent. stream – (optional) Whether to stream the request content. timeout – (optional) The timeout on the request. verify – (optional) Whether to verify SSL certificates. vert – (optional) Any user-provided SSL certificate to be trusted. proxies – (optional) The proxies dictionary to apply to the request.

Migrando para 1.x¶

Essa seção detalha as principais diferenças entre 0.x e 1.x e é feita para facilitar a dor da atualização.

Mudanças na API¶

Response.json agora é chamável e não uma propriedade de Response.

import requests
r = requests.get('https://github.com/timeline.json')
r.json()   # Essa *chamada* levanta uma exceção quando a decodificação do JSON falha

A API de Session mudou. Objetos Session não aceitam mais parâmetros. Session agora é capitalizado, mas ainda pode ser instanciado com o session minúsculo para retrocompatibilidade.
```
s = requests.Session()    # originalmente, session recebia parâmetros
s.auth = auth
s.headers.update(headers)
r = s.get('http://httpbin.org/headers')
```
Todos os hooks de requisição foram removidos com exceção de ‘response’.
Helpers de autenticação foram quebrados em módulos separados. Veja requests-oauthlib and requests-kerberos.

O parâmetro para requisições de streaming oram mudados de prefetch para stream e a lógica foi invertida. Além disso, stream agora é exigido para leitura de resposta crua.
```
# na 0.x, passando prefetch=False iria realizar a mesma coisa
r = requests.get('https://github.com/timeline.json', stream=True)
r.raw.read(10)
```

O parâmetro config dos métodos de requisição foi removido. Algumas das opções agora são configuradas em um objeto Session como keep-alive e o número máximo de redirecionamentos. A opção de verbosidade deve ser manipulada pela configuração de logging.

import requests
import logging

# essas duas linhas habilitam debugging no nível do httplib (requests->urllib3->httplib)
# você verá o REQUEST, incluindo HEADERS e DATA, e RESPONSE com HEADERS mas sem DATA.
# a única coisa faltando será o response.body que não será registrado.
import httplib
httplib.HTTPConnection.debuglevel = 1

logging.basicConfig() # você precisa inicializar o logging, se não você não verá nada
logging.getLogger().setLevel(logging.DEBUG)
requests_log = logging.getLogger("requests.packages.urllib3")
requests_log.setLevel(logging.DEBUG)
requests_log.propagate = True

requests.get('http://httpbin.org/headers')

Licensa¶

Uma diferença importante que não é relacionada com a API é a mudança da licensa do ISC para a licensa Apache 2.0. A licensa Apache 2.0 garante que as contribuições para requests também estão cobertas pela licensa Apache 2.0.

Guia de Contribuição¶

Se você quiser contribuir para o projeto, esta parte da documentação é para você.

Filosofia de desenvolvimento¶

Requests é uma biblioteca aberta porém teimosa, criado por um desenvolvedor aberto porém teimoso.

Ditador Benevolente¶

Kenneth Reitz é o BDFL (Ditador Benevolente para a Vida). Ele tem a palavra final em qualquer discussão relacionada ao Requests.

Valores¶

Simplicidade é sempre melhor que funcionalidade.
Ouça a todos, então, ignore.
A API é tudo o que importa. Todo o restante é secundário.
Satisfaça 90% dos casos de uso. Ignore os opositores.

Versionamento semântico¶

Durante muitos anos, a comunidade open source tem sofrido com distonia dos números das versões. Números variam tanto de projeto para projeto, que são praticamente sem significado.

Requests usa Versionamento Semântico. Esta especificação procura por um fim nesta confusão com um pequeno número de sugestões práticas para você e seus colegas usaremos no seu próximo projeto.

Biblioteca padrão?¶

Requests não tem planos ativos de ser incluída na biblioteca padrão. Esta discussão tem sido longamente discutida com Guido assim como vários desenvolvedores do núcleo do Python.

Essencialmente, a biblioteca padrão é onde uma biblioteca vai para morrer. É apropriado para um módulo ser incluído quando não há mais necessidade de desenvolvimento ativo.

Requests acabou de chegar na versão v1.0.0. Este grande marco representa um grande passo na direção correta.

Pacotes de distribuições Linux¶

Pacotes têm sido feitos para várias distribuições Linux, incluindo: Ubuntu, Debian, RHEL e Arch.

Às vezes, estes pacotes são forks divergentes, ou não são mantidos atualizados com o código e correções mais atuais. PyPI (e seus mirrors) e o GitHub são as fontes oficiais de distribuição; alternativas não são suportadas pelo projeto requests.

Como Ajudar¶

Requests está sob desenvolvimento ativo e contribuições são mais que bem-vindas!

Procure por issues abertas ou abra uma nova issue para começar uma discussão sobre um bug. Existe um tag Contributor Friendly para issues que são ideais para pessoas que não estão muito familiarizadas com a base de código ainda.
Faça um fork do repositório no GitHub e comece a fazer suas mudanças em uma nova branch.
Escreva um teste que mostra que seu bug foi corrigido.
Crie um pull request e avise o mantenedor até que seja aceito e publicado. :) Certifique-se de se adicionar no arquivo AUTHORS.

Congelamento de funcionalidades¶

A partir da versão v1.0.0., Requests entrou num período de congelamento de funcionalidades. Pedidos de novas funcionalidades e Pull Requests implementando-as não serão aceitos.

Dependências de desenvolvimento¶

Você vai precisar instalar py.test para rodar a suíte de tests de Requests:

$ pip install -r requirements.txt
$ invoke test
py.test
platform darwin -- Python 2.7.3 -- pytest-2.3.4
collected 25 items

test_requests.py .........................
25 passed in 3.50 seconds

Ambientes de execução¶

Requests atualmente suporta as seguintes versões do Python:

Python 2.6
Python 2.7
Python 3.1
Python 3.2
Python 3.3
PyPy 1.9

Suporte para Python 3.1 e 3.2 pode ser descontinuado a qualquer momento.

Google App Engine nunca será oficialmente suportado. Pull requests para compatibilidade serão aceitos, desde que eles não compliquem a base código.

Você está louco?¶

Suporte a SPDY seria fantástico. Sem extensões em C.

Autores¶

Requests is written and maintained by Kenneth Reitz and various contributors:

Development Lead¶

Kenneth Reitz <me@kennethreitz.com>

Urllib3¶

Andrey Petrov <andrey.petrov@shazow.net>

Patches and Suggestions¶

Various Pocoo Members
Chris Adams
Flavio Percoco Premoli
Dj Gilcrease
Justin Murphy
Rob Madole
Aram Dulyan
Johannes Gorset
村山めがね (Megane Murayama)
James Rowe
Daniel Schauenberg
Zbigniew Siciarz
Daniele Tricoli ‘Eriol’
Richard Boulton
Miguel Olivares <miguel@moliware.com>
Alberto Paro
Jérémy Bethmont
潘旭 (Xu Pan)
Tamás Gulácsi
Rubén Abad
Peter Manser
Jeremy Selier
Jens Diemer
Alex <@alopatin>
Tom Hogans <tomhsx@gmail.com>
Armin Ronacher
Shrikant Sharat Kandula
Mikko Ohtamaa
Den Shabalin
Daniel Miller <danielm@vs-networks.com>
Alejandro Giacometti
Rick Mak
Johan Bergström
Josselin Jacquard
Travis N. Vaught
Fredrik Möllerstrand
Daniel Hengeveld
Dan Head
Bruno Renié
David Fischer
Joseph McCullough
Juergen Brendel
Juan Riaza
Ryan Kelly
Rolando Espinoza La fuente
Robert Gieseke
Idan Gazit
Ed Summers
Chris Van Horne
Christopher Davis
Ori Livneh
Jason Emerick
Bryan Helmig
Jonas Obrist
Lucian Ursu
Tom Moertel
Frank Kumro Jr
Chase Sterling
Marty Alchin
takluyver
Ben Toews (mastahyeti)
David Kemp
Brendon Crawford
Denis (Telofy)
Cory Benfield (Lukasa)
Matt Giuca
Adam Tauber
Honza Javorek
Brendan Maguire <maguire.brendan@gmail.com>
Chris Dary
Danver Braganza <danverbraganza@gmail.com>
Max Countryman
Nick Chadwick
Jonathan Drosdeck
Jiri Machalek
Steve Pulec
Michael Kelly
Michael Newman <newmaniese@gmail.com>
Jonty Wareing <jonty@jonty.co.uk>
Shivaram Lingamneni
Miguel Turner
Rohan Jain (crodjer)
Justin Barber <barber.justin@gmail.com>
Roman Haritonov <@reclosedev>
Josh Imhoff <joshimhoff13@gmail.com>
Arup Malakar <amalakar@gmail.com>
Danilo Bargen (dbrgn)
Torsten Landschoff
Michael Holler (apotheos)
Timnit Gebru
Sarah Gonzalez
Victoria Mo
Leila Muhtasib
Matthias Rahlf <matthias@webding.de>
Jakub Roztocil <jakub@roztocil.name>
Ian Cordasco <graffatcolmingov@gmail.com> @sigmavirus24
Rhys Elsmore
André Graf (dergraf)
Stephen Zhuang (everbird)
Martijn Pieters
Jonatan Heyman
David Bonner <dbonner@gmail.com> @rascalking
Vinod Chandru
Johnny Goodnow <j.goodnow29@gmail.com>
Denis Ryzhkov <denisr@denisr.com>
Wilfred Hughes <me@wilfred.me.uk> @dontYetKnow
Dmitry Medvinsky <me@dmedvinsky.name>

Navegação

Requests: HTTP para Humanos¶

Depoimentos¶

Funcionalidades¶

Guia do Usuário¶

Introdução¶

Filosofia¶

Licensa Apache2¶

Licensa do Requests¶

Instalação¶

Distribute e Pip¶

Cheeseshop Mirror¶

Usando o código¶

Guia de início rápido¶

Fazer uma requisição¶

Passando parâmetros em URLs¶

Conteúdo da resposta¶

Resposta binária¶

Respota JSON¶

Resposta crua¶

Cabeçalhos personalizados¶

Requisições POST mais complicadas¶

POST de arquivo Multipart¶

Código do status da resposta¶

Cabeçalhos da resposta¶

Cookies¶

Redirecionamento e Histórico¶

Timeouts¶

Erros e Exceções¶

Uso avançado¶

Objetos Session¶

Objetos Request e Response¶

Requisições preparadas¶

Verificação de certificado SSL¶

Fluxo do conteúdo do corpo¶

Keep-Alive¶

Uploads com Streaming¶

Requisições com blocos codificados¶

Hooks de eventos¶

Autenticação personalizada¶

Requisições de Streaming¶

Proxies¶

Concordância¶

Codificações¶

Verbos HTTP¶

Cabeçalhos Link¶

Transport Adapters¶

Autenticação¶

HTTP Basic Auth¶

Autenticação Digest¶

Autenticação com OAuth 1¶

Outras formas de autenticação¶

Novas formas de autenticação¶

Guia da Comunidade¶

FAQ¶

Dados codificados?¶

User-Agents personalizados?¶

Por que não Httplib2?¶

Suporte ao Python 3?¶

Integrações¶

ScraperWiki¶

Python para iOS¶

Artigos e Palestras¶

Suporte¶

Envie um Tweet¶

Criar uma Issue¶

E-mail¶

IRC¶

Atualizações¶

GitHub¶

Twitter¶

Lista de e-mails¶

Documentação da API¶

Interface de Desenvolvedor¶

Interface principal¶

Classes baixo-nível¶

Sessões de requisição¶

Exceções¶

Referência de código de status¶

Cookies¶