API Reference

register_uri

classmethod httpretty.register_uri(method, uri, body='{"message": "HTTPretty :)"}', adding_headers=None, forcing_headers=None, status=200, responses=None, match_querystring=False, priority=0, **headers)[source]
import httpretty


def request_callback(request, uri, response_headers):
    content_type = request.headers.get('Content-Type')
    assert request.body == '{"nothing": "here"}', 'unexpected body: {}'.format(request.body)
    assert content_type == 'application/json', 'expected application/json but received Content-Type: {}'.format(content_type)
    return [200, response_headers, json.dumps({"hello": "world"})]

httpretty.register_uri(
    HTTPretty.POST, "https://httpretty.example.com/api",
    body=request_callback)


with httpretty.enabled():
    requests.post('https://httpretty.example.com/api', data='{"nothing": "here"}', headers={'Content-Type': 'application/json'})

assert httpretty.latest_requests[-1].url == 'https://httpbin.org/ip'
Parameters
  • method – one of httpretty.GET, httpretty.PUT, httpretty.POST, httpretty.DELETE, httpretty.HEAD, httpretty.PATCH, httpretty.OPTIONS, httpretty.CONNECT

  • uri – a string or regex pattern (e.g.: “https://httpbin.org/ip”)

  • body – a string, defaults to {"message": "HTTPretty :)"}

  • adding_headers – dict - headers to be added to the response

  • forcing_headers – dict - headers to be forcefully set in the response

  • status – an integer, defaults to 200

  • responses – a list of entries, ideally each created with Response()

  • priority – an integer, useful for setting higher priority over previously registered urls. defaults to zero

  • match_querystring – bool - whether to take the querystring into account when matching an URL

  • headers – headers to be added to the response

Warning

When using a port in the request, add a trailing slash if no path is provided otherwise Httpretty will not catch the request. Ex: httpretty.register_uri(httpretty.GET, 'http://fakeuri.com:8080/', body='{"hello":"world"}')

enable

classmethod httpretty.enable(allow_net_connect=True, verbose=False)[source]

Enables HTTPretty.

Parameters
  • allow_net_connect – boolean to determine if unmatched requests are forwarded to a real network connection OR throw httpretty.errors.UnmockedError.

  • verbose – boolean to set HTTPretty’s logging level to DEBUG

import re, json
import httpretty

httpretty.enable(allow_net_connect=True, verbose=True)

httpretty.register_uri(
    httpretty.GET,
    re.compile(r'http://.*'),
    body=json.dumps({'man': 'in', 'the': 'middle'})
)

response = requests.get('https://foo.bar/foo/bar')

response.json().should.equal({
    "man": "in",
    "the": "middle",
})

Warning

after calling this method the original socket is replaced with httpretty.core.fakesock. Make sure to call disable() after done with your tests or use the httpretty.enabled as decorator or context-manager

disable

classmethod httpretty.disable()[source]

Disables HTTPretty entirely, putting the original socket module back in its place.

import re, json
import httpretty

httpretty.enable()
# request passes through fake socket
response = requests.get('https://httpbin.org')

httpretty.disable()
# request uses real python socket module
response = requests.get('https://httpbin.org')

Note

This method does not call httpretty.core.reset() automatically.

is_enabled

classmethod httpretty.is_enabled()[source]

Check if HTTPretty is enabled

Returns

bool

import httpretty

httpretty.enable()
assert httpretty.is_enabled() == True

httpretty.disable()
assert httpretty.is_enabled() == False

last_request

httpretty.last_request()[source]
Returns

the last HTTPrettyRequest

latest_requests

httpretty.latest_requests()[source]

returns the history of made requests

activate

httpretty.activate

alias of httpretty.core.httprettified

httprettified

httpretty.core.httprettified(test=None, allow_net_connect=True, verbose=False)[source]

decorator for test functions

Tip

Also available under the alias httpretty.activate()

Parameters

test – a callable

example usage with nosetests

import sure
from httpretty import httprettified

@httprettified
def test_using_nosetests():
    httpretty.register_uri(
        httpretty.GET,
        'https://httpbin.org/ip'
    )

    response = requests.get('https://httpbin.org/ip')

    response.json().should.equal({
        "message": "HTTPretty :)"
    })

example usage with unittest module

import unittest
from sure import expect
from httpretty import httprettified

@httprettified
class TestWithPyUnit(unittest.TestCase):
    def test_httpbin(self):
        httpretty.register_uri(httpretty.GET, 'https://httpbin.org/ip')
        response = requests.get('https://httpbin.org/ip')
        expect(response.json()).to.equal({
            "message": "HTTPretty :)"
        })

enabled

httpretty.enabled

alias of httpretty.core.httprettized

httprettized

class httpretty.core.httprettized(allow_net_connect=True, verbose=False)[source]

context-manager for enabling HTTPretty.

Tip

Also available under the alias httpretty.enabled()

import json
import httpretty

httpretty.register_uri(httpretty.GET, 'https://httpbin.org/ip', body=json.dumps({'origin': '42.42.42.42'}))
with httpretty.enabled():
    response = requests.get('https://httpbin.org/ip')

assert httpretty.latest_requests[-1].url == 'https://httpbin.org/ip'
assert response.json() == {'origin': '42.42.42.42'}

HTTPrettyRequest

class httpretty.core.HTTPrettyRequest(headers, body='', sock=None, path_encoding='iso-8859-1')[source]

Represents a HTTP request. It takes a valid multi-line, \r\n separated string with HTTP headers and parse them out using the internal parse_request method.

It also replaces the rfile and wfile attributes with io.BytesIO instances so that we guarantee that it won’t make any I/O, neither for writing nor reading.

It has some convenience attributes:

headers -> a mimetype object that can be cast into a dictionary, contains all the request headers

protocol -> the protocol of this host, inferred from the port of the underlying fake TCP socket.

host -> the hostname of this request.

url -> the full url of this request.

path -> the path of the request.

method -> the HTTP method used in this request.

querystring -> a dictionary containing lists with the attributes. Please notice that if you need a single value from a query string you will need to get it manually like:

body -> the request body as a string.

parsed_body -> the request body parsed by parse_request_body.

>>> request.querystring
{'name': ['Gabriel Falcao']}
>>> print request.querystring['name'][0]
property method

the HTTP method used in this request

parse_querystring(qs)[source]

parses an UTF-8 encoded query string into a dict of string lists

Parameters

qs – a querystring

Returns

a dict of lists

parse_request_body(body)[source]

Attempt to parse the post based on the content-type passed. Return the regular body if not

Parameters

body – string

Returns

a python object such as dict or list in case the deserialization suceeded. Else returns the given param body

property protocol

the protocol used in this request

querystring

a dictionary containing parsed request body or None if HTTPrettyRequest doesn’t know how to parse it. It currently supports parsing body data that was sent under the content`-type` headers values: ``application/json or application/x-www-form-urlencoded

property url

the full url of this recorded request

HTTPrettyRequestEmpty

class httpretty.core.HTTPrettyRequestEmpty[source]

Represents an empty HTTPrettyRequest where all its properties are somehow empty or None

FakeSockFile

class httpretty.core.FakeSockFile[source]

Fake socket file descriptor. Under the hood all data is written in a temporary file, giving it a real file descriptor number.

FakeSSLSocket

class httpretty.core.FakeSSLSocket(sock, *args, **kw)[source]

Shorthand for fakesock

URIInfo

class httpretty.URIInfo(username='', password='', hostname='', port=80, path='/', query='', fragment='', scheme='', last_request=None)[source]

Internal representation of URIs

Tip

all arguments are optional

Parameters
  • username

  • password

  • hostname

  • port

  • path

  • query

  • fragment

  • scheme

  • last_request

classmethod from_uri(uri, entry)[source]
Parameters
  • uri – string

  • entry – an instance of Entry

full_url(use_querystring=True)[source]
Parameters

use_querystring – bool

Returns

a string with the full url with the format {scheme}://{credentials}{domain}{path}{query}

get_full_domain()[source]
Returns

a string in the form {domain}:{port} or just the domain if the port is 80 or 443

URIMatcher

class httpretty.URIMatcher(uri, entries, match_querystring=False, priority=0)[source]
get_next_entry(method, info, request)[source]

Cycle through available responses, but only once. Any subsequent requests will receive the last response

Entry

class httpretty.Entry(method, uri, body, adding_headers=None, forcing_headers=None, status=200, streaming=False, **headers)[source]

Created by register_uri() and stored in memory as internal representation of a HTTP request/response definition.

Parameters
  • method (str) – One of httpretty.GET, httpretty.PUT, httpretty.POST, httpretty.DELETE, httpretty.HEAD, httpretty.PATCH, httpretty.OPTIONS, httpretty.CONNECT.

  • uri (str|re.Pattern) – The URL to match

  • adding_headers (dict) – Extra headers to be added to the response

  • forcing_headers (dict) – Overwrite response headers.

  • status (int) – The status code for the response, defaults to 200.

  • streaming (bool) – Whether should stream the response into chunks via generator.

  • headers – Headers to inject in the faked response.

Returns

containing the request-matching metadata.

Return type

httpretty.Entry

Warning

When using the forcing_headers option make sure to add the header Content-Length to match at most the total body length, otherwise some HTTP clients can hang indefinitely.

fill_filekind(fk)[source]

writes HTTP Response data to a file descriptor

Parm fk

a file-like object

Warning

side-effect: this method moves the cursor of the given file object to zero

normalize_headers(headers)[source]

Normalize keys in header names so that COntent-tyPe becomes content-type

Parameters

headers – dict

Returns

dict

validate()[source]

validates the body size with the value of the Content-Length header

Modules

Core

class httpretty.core.EmptyRequestHeaders[source]

A dict subclass used as internal representation of empty request headers

class httpretty.core.Entry(method, uri, body, adding_headers=None, forcing_headers=None, status=200, streaming=False, **headers)[source]

Created by register_uri() and stored in memory as internal representation of a HTTP request/response definition.

Parameters
  • method (str) – One of httpretty.GET, httpretty.PUT, httpretty.POST, httpretty.DELETE, httpretty.HEAD, httpretty.PATCH, httpretty.OPTIONS, httpretty.CONNECT.

  • uri (str|re.Pattern) – The URL to match

  • adding_headers (dict) – Extra headers to be added to the response

  • forcing_headers (dict) – Overwrite response headers.

  • status (int) – The status code for the response, defaults to 200.

  • streaming (bool) – Whether should stream the response into chunks via generator.

  • headers – Headers to inject in the faked response.

Returns

containing the request-matching metadata.

Return type

httpretty.Entry

Warning

When using the forcing_headers option make sure to add the header Content-Length to match at most the total body length, otherwise some HTTP clients can hang indefinitely.

fill_filekind(fk)[source]

writes HTTP Response data to a file descriptor

Parm fk

a file-like object

Warning

side-effect: this method moves the cursor of the given file object to zero

normalize_headers(headers)[source]

Normalize keys in header names so that COntent-tyPe becomes content-type

Parameters

headers – dict

Returns

dict

validate()[source]

validates the body size with the value of the Content-Length header

class httpretty.core.FakeSSLSocket(sock, *args, **kw)[source]

Shorthand for fakesock

class httpretty.core.FakeSockFile[source]

Fake socket file descriptor. Under the hood all data is written in a temporary file, giving it a real file descriptor number.

class httpretty.core.HTTPrettyRequest(headers, body='', sock=None, path_encoding='iso-8859-1')[source]

Represents a HTTP request. It takes a valid multi-line, \r\n separated string with HTTP headers and parse them out using the internal parse_request method.

It also replaces the rfile and wfile attributes with io.BytesIO instances so that we guarantee that it won’t make any I/O, neither for writing nor reading.

It has some convenience attributes:

headers -> a mimetype object that can be cast into a dictionary, contains all the request headers

protocol -> the protocol of this host, inferred from the port of the underlying fake TCP socket.

host -> the hostname of this request.

url -> the full url of this request.

path -> the path of the request.

method -> the HTTP method used in this request.

querystring -> a dictionary containing lists with the attributes. Please notice that if you need a single value from a query string you will need to get it manually like:

body -> the request body as a string.

parsed_body -> the request body parsed by parse_request_body.

>>> request.querystring
{'name': ['Gabriel Falcao']}
>>> print request.querystring['name'][0]
property method

the HTTP method used in this request

parse_querystring(qs)[source]

parses an UTF-8 encoded query string into a dict of string lists

Parameters

qs – a querystring

Returns

a dict of lists

parse_request_body(body)[source]

Attempt to parse the post based on the content-type passed. Return the regular body if not

Parameters

body – string

Returns

a python object such as dict or list in case the deserialization suceeded. Else returns the given param body

property protocol

the protocol used in this request

querystring

a dictionary containing parsed request body or None if HTTPrettyRequest doesn’t know how to parse it. It currently supports parsing body data that was sent under the content`-type` headers values: ``application/json or application/x-www-form-urlencoded

property url

the full url of this recorded request

class httpretty.core.HTTPrettyRequestEmpty[source]

Represents an empty HTTPrettyRequest where all its properties are somehow empty or None

class httpretty.core.URIInfo(username='', password='', hostname='', port=80, path='/', query='', fragment='', scheme='', last_request=None)[source]

Internal representation of URIs

Tip

all arguments are optional

Parameters
  • username

  • password

  • hostname

  • port

  • path

  • query

  • fragment

  • scheme

  • last_request

classmethod from_uri(uri, entry)[source]
Parameters
  • uri – string

  • entry – an instance of Entry

full_url(use_querystring=True)[source]
Parameters

use_querystring – bool

Returns

a string with the full url with the format {scheme}://{credentials}{domain}{path}{query}

get_full_domain()[source]
Returns

a string in the form {domain}:{port} or just the domain if the port is 80 or 443

httpretty.core.create_fake_connection(address, timeout=<object object>, source_address=None)[source]

drop-in replacement for socket.create_connection()

httpretty.core.fake_getaddrinfo(host, port, family=None, socktype=None, proto=None, flags=None)[source]

drop-in replacement for socket.getaddrinfo()

httpretty.core.fake_gethostbyname(host)[source]

drop-in replacement for socket.gethostbyname()

httpretty.core.fake_gethostname()[source]

drop-in replacement for socket.gethostname()

httpretty.core.fake_wrap_socket(orig_wrap_socket_fn, *args, **kw)[source]

drop-in replacement for py:func:ssl.wrap_socket

class httpretty.core.fakesock[source]

fake socket

class socket(family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0, fileno=None)[source]

drop-in replacement for socket.socket

makefile(mode='r', bufsize=- 1)[source]

Returns this fake socket’s own tempfile buffer.

If there is an entry associated with the socket, the file descriptor gets filled in with the entry data before being returned.

real_sendall(data, *args, **kw)[source]

Sends data to the remote server. This method is called when HTTPretty identifies that someone is trying to send non-http data.

The received bytes are written in this socket’s tempfile buffer so that HTTPretty can return it accordingly when necessary.

httpretty.core.get_default_thread_timeout()[source]

sets the default thread timeout for HTTPretty threads

Returns

int

httpretty.core.httprettified(test=None, allow_net_connect=True, verbose=False)[source]

decorator for test functions

Tip

Also available under the alias httpretty.activate()

Parameters

test – a callable

example usage with nosetests

import sure
from httpretty import httprettified

@httprettified
def test_using_nosetests():
    httpretty.register_uri(
        httpretty.GET,
        'https://httpbin.org/ip'
    )

    response = requests.get('https://httpbin.org/ip')

    response.json().should.equal({
        "message": "HTTPretty :)"
    })

example usage with unittest module

import unittest
from sure import expect
from httpretty import httprettified

@httprettified
class TestWithPyUnit(unittest.TestCase):
    def test_httpbin(self):
        httpretty.register_uri(httpretty.GET, 'https://httpbin.org/ip')
        response = requests.get('https://httpbin.org/ip')
        expect(response.json()).to.equal({
            "message": "HTTPretty :)"
        })
class httpretty.core.httprettized(allow_net_connect=True, verbose=False)[source]

context-manager for enabling HTTPretty.

Tip

Also available under the alias httpretty.enabled()

import json
import httpretty

httpretty.register_uri(httpretty.GET, 'https://httpbin.org/ip', body=json.dumps({'origin': '42.42.42.42'}))
with httpretty.enabled():
    response = requests.get('https://httpbin.org/ip')

assert httpretty.latest_requests[-1].url == 'https://httpbin.org/ip'
assert response.json() == {'origin': '42.42.42.42'}
class httpretty.core.httpretty[source]

manages HTTPretty’s internal request/response registry and request matching.

classmethod Response(body, method=None, uri=None, adding_headers=None, forcing_headers=None, status=200, streaming=False, **kw)[source]

Shortcut to create an Entry that takes the body as first positional argument.

See also

the parameters of this function match those of the Entry constructor.

Parameters
  • body (str) – The body to return as response..

  • method (str) – One of httpretty.GET, httpretty.PUT, httpretty.POST, httpretty.DELETE, httpretty.HEAD, httpretty.PATCH, httpretty.OPTIONS, httpretty.CONNECT.

  • uri (str|re.Pattern) – The URL to match

  • adding_headers (dict) – Extra headers to be added to the response

  • forcing_headers (dict) – Overwrite any response headers, even “Content-Length”.

  • status (int) – The status code for the response, defaults to 200.

  • streaming (bool) – Whether should stream the response into chunks via generator.

  • kwargs – Keyword-arguments are forwarded to Entry

Returns

containing the request-matching metadata.

Return type

httpretty.Entry

classmethod disable()[source]

Disables HTTPretty entirely, putting the original socket module back in its place.

import re, json
import httpretty

httpretty.enable()
# request passes through fake socket
response = requests.get('https://httpbin.org')

httpretty.disable()
# request uses real python socket module
response = requests.get('https://httpbin.org')

Note

This method does not call httpretty.core.reset() automatically.

classmethod enable(allow_net_connect=True, verbose=False)[source]

Enables HTTPretty.

Parameters
  • allow_net_connect – boolean to determine if unmatched requests are forwarded to a real network connection OR throw httpretty.errors.UnmockedError.

  • verbose – boolean to set HTTPretty’s logging level to DEBUG

import re, json
import httpretty

httpretty.enable(allow_net_connect=True, verbose=True)

httpretty.register_uri(
    httpretty.GET,
    re.compile(r'http://.*'),
    body=json.dumps({'man': 'in', 'the': 'middle'})
)

response = requests.get('https://foo.bar/foo/bar')

response.json().should.equal({
    "man": "in",
    "the": "middle",
})

Warning

after calling this method the original socket is replaced with httpretty.core.fakesock. Make sure to call disable() after done with your tests or use the httpretty.enabled as decorator or context-manager

classmethod historify_request(headers, body='', sock=None, append=True)[source]

appends request to a list for later retrieval

import httpretty

httpretty.register_uri(httpretty.GET, 'https://httpbin.org/ip', body='')
with httpretty.enabled():
    requests.get('https://httpbin.org/ip')

assert httpretty.latest_requests[-1].url == 'https://httpbin.org/ip'
classmethod is_enabled()[source]

Check if HTTPretty is enabled

Returns

bool

import httpretty

httpretty.enable()
assert httpretty.is_enabled() == True

httpretty.disable()
assert httpretty.is_enabled() == False
classmethod match_http_address(hostname, port)[source]
Parameters
  • hostname – a string

  • port – an integer

Returns

an URLMatcher or None

classmethod match_https_hostname(hostname)[source]
Parameters

hostname – a string

Returns

an URLMatcher or None

classmethod match_uriinfo(info)[source]
Parameters

info – an URIInfo

Returns

a 2-item tuple: (URLMatcher, URIInfo) or (None, [])

classmethod playback(filename, allow_net_connect=True, verbose=False)[source]
import io
import json
import requests
import httpretty

with httpretty.record('/tmp/ip.json'):
    data = requests.get('https://httpbin.org/ip').json()

with io.open('/tmp/ip.json') as fd:
    assert data == json.load(fd)
Parameters

filename – a string

Returns

a context-manager

classmethod record(filename, indentation=4, encoding='utf-8', verbose=False, allow_net_connect=True, pool_manager_params=None)[source]
import io
import json
import requests
import httpretty

with httpretty.record('/tmp/ip.json'):
    data = requests.get('https://httpbin.org/ip').json()

with io.open('/tmp/ip.json') as fd:
    assert data == json.load(fd)
Parameters
  • filename – a string

  • indentation – an integer, defaults to 4

  • encoding – a string, defaults to “utf-8”

Returns

a context-manager

classmethod register_uri(method, uri, body='{"message": "HTTPretty :)"}', adding_headers=None, forcing_headers=None, status=200, responses=None, match_querystring=False, priority=0, **headers)[source]
import httpretty


def request_callback(request, uri, response_headers):
    content_type = request.headers.get('Content-Type')
    assert request.body == '{"nothing": "here"}', 'unexpected body: {}'.format(request.body)
    assert content_type == 'application/json', 'expected application/json but received Content-Type: {}'.format(content_type)
    return [200, response_headers, json.dumps({"hello": "world"})]

httpretty.register_uri(
    HTTPretty.POST, "https://httpretty.example.com/api",
    body=request_callback)


with httpretty.enabled():
    requests.post('https://httpretty.example.com/api', data='{"nothing": "here"}', headers={'Content-Type': 'application/json'})

assert httpretty.latest_requests[-1].url == 'https://httpbin.org/ip'
Parameters
  • method – one of httpretty.GET, httpretty.PUT, httpretty.POST, httpretty.DELETE, httpretty.HEAD, httpretty.PATCH, httpretty.OPTIONS, httpretty.CONNECT

  • uri – a string or regex pattern (e.g.: “https://httpbin.org/ip”)

  • body – a string, defaults to {"message": "HTTPretty :)"}

  • adding_headers – dict - headers to be added to the response

  • forcing_headers – dict - headers to be forcefully set in the response

  • status – an integer, defaults to 200

  • responses – a list of entries, ideally each created with Response()

  • priority – an integer, useful for setting higher priority over previously registered urls. defaults to zero

  • match_querystring – bool - whether to take the querystring into account when matching an URL

  • headers – headers to be added to the response

Warning

When using a port in the request, add a trailing slash if no path is provided otherwise Httpretty will not catch the request. Ex: httpretty.register_uri(httpretty.GET, 'http://fakeuri.com:8080/', body='{"hello":"world"}')

classmethod reset()[source]

resets the internal state of HTTPretty, unregistering all URLs

httpretty.core.set_default_thread_timeout(timeout)[source]

sets the default thread timeout for HTTPretty threads

Parameters

timeout – int

httpretty.core.url_fix(s, charset=None)[source]

escapes special characters

Http

httpretty.http.last_requestline(sent_data)[source]

Find the last line in sent_data that can be parsed with parse_requestline

httpretty.http.parse_requestline(s)[source]

http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5

>>> parse_requestline('GET / HTTP/1.0')
('GET', '/', '1.0')
>>> parse_requestline('post /testurl htTP/1.1')
('POST', '/testurl', '1.1')
>>> parse_requestline('Im not a RequestLine')
Traceback (most recent call last):
    ...
ValueError: Not a Request-Line

Utils

Exceptions

exception httpretty.errors.HTTPrettyError[source]
exception httpretty.errors.UnmockedError(message='Failed to handle network request', request=None, address=None)[source]