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 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¶
- 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
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 headersprotocol
-> 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 byparse_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
orapplication/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 orNone
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.
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 –
- 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¶
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 headerContent-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
becomescontent-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 headerContent-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
- 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 headersprotocol
-> 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 byparse_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
orapplication/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 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>, proto=0, fileno=None)[source]¶
drop-in replacement for
socket.socket
- property host¶
- 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.
- 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 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='', sock=None)[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 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
- 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
- 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"}')
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