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 (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
- method – one of
enable¶
-
classmethod
httpretty.
enable
(allow_net_connect=True)[source]¶ Enables HTTPretty. When
allow_net_connect
isFalse
any connection to an unregistered uri will throwhttpretty.errors.UnmockedError
.import re, json import httpretty httpretty.enable() 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 withhttpretty.core.fakesock
. Make sure to calldisable()
after done with your tests or use thehttpretty.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¶
last_request¶
-
httpretty.
last_request
()[source]¶ Returns: the last HTTPrettyRequest
activate¶
-
httpretty.
activate
¶ alias of
httpretty.core.httprettified
httprettified¶
-
class
httpretty.core.
httprettified
[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 :)" })
httprettized¶
-
class
httpretty.core.
httprettized
(allow_net_connect=True)[source]¶ context-manager for enabling HTTPretty.
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='')[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 StringIO instances so that we guarantee that it won’t make any I/O, neighter for writing nor reading.
It has some convenience attributes:
headers
-> a mimetype object that can be cast into a dictionary, contains all the request headersmethod
-> the HTTP method used in this requestquerystring
-> 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 stringparsed_body
-> the request body parsed byparse_request_body
>>> request.querystring {'name': ['Gabriel Falcao']} >>> print request.querystring['name'][0]
-
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
-
querystring
= None¶ 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
orapplication/x-www-form-urlencoded
-
HTTPrettyRequestEmpty¶
-
class
httpretty.core.
HTTPrettyRequestEmpty
[source]¶ Represents an empty
HTTPrettyRequest
where all its properties are somehow empty orNone
FakeSockFile¶
FakeSSLSocket¶
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 –
URIMatcher¶
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 – string
- uri – string
- body – string
- adding_headers – dict - headers to be added to the response
- forcing_headers – dict - headers to be forcefully set in the response
- status – an integer (e.g.:
status=200
) - streaming – bool - whether to stream the response
- headers – keyword-args with headers to be added to the response
Warning
When using the
forcing_headers
option make sure to add the headerContent-Length
otherwise calls usingrequests
will try to load the response endlessly.-
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
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 – string
- uri – string
- body – string
- adding_headers – dict - headers to be added to the response
- forcing_headers – dict - headers to be forcefully set in the response
- status – an integer (e.g.:
status=200
) - streaming – bool - whether to stream the response
- headers – keyword-args with headers to be added to the response
Warning
When using the
forcing_headers
option make sure to add the headerContent-Length
otherwise calls usingrequests
will try to load the response endlessly.-
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
-
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='')[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 StringIO instances so that we guarantee that it won’t make any I/O, neighter for writing nor reading.
It has some convenience attributes:
headers
-> a mimetype object that can be cast into a dictionary, contains all the request headersmethod
-> the HTTP method used in this requestquerystring
-> 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 stringparsed_body
-> the request body parsed byparse_request_body
>>> request.querystring {'name': ['Gabriel Falcao']} >>> print request.querystring['name'][0]
-
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
-
querystring
= None 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
orapplication/x-www-form-urlencoded
-
-
class
httpretty.core.
HTTPrettyRequestEmpty
[source] Represents an empty
HTTPrettyRequest
where all its properties are somehow empty orNone
-
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 –
-
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: 2>, type=<SocketKind.SOCK_STREAM: 1>, protocol=0, _sock=None)[source]¶ drop-in replacement for
socket.socket
-
class
-
httpretty.core.
httprettified
(test=None, allow_net_connect=True)[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)[source] context-manager for enabling HTTPretty.
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 argumentSee also
the parameters of this function match those of the
Entry
constructorParameters: - body –
- method – one of
httpretty.GET
,httpretty.PUT
,httpretty.POST
,httpretty.DELETE
,httpretty.HEAD
,httpretty.PATCH
,httpretty.OPTIONS
,httpretty.CONNECT
- uri –
- adding_headers –
- forcing_headers –
- status – defaults to 200
- streaming – defaults to False
- kw – keyword-arguments passed onto the
Entry
Returns: an
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)[source] Enables HTTPretty. When
allow_net_connect
isFalse
any connection to an unregistered uri will throwhttpretty.errors.UnmockedError
.import re, json import httpretty httpretty.enable() 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 withhttpretty.core.fakesock
. Make sure to calldisable()
after done with your tests or use thehttpretty.enabled
as decorator or context-manager
-
classmethod
historify_request
(headers, body='', 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
orNone
-
classmethod
match_https_hostname
(hostname)[source]¶ Parameters: hostname – a string Returns: an URLMatcher
orNone
-
classmethod
match_uriinfo
(info)[source]¶ Parameters: info – an URIInfo
Returns: a 2-item tuple: ( URLMatcher
,URIInfo
) or(None, [])
-
classmethod
playback
(filename)[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')[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:
-
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 (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
- method – one of
-
classmethod
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