2
# Copyright 2008-2013 Andrey Petrov and contributors (see CONTRIBUTORS.txt)
4
# This module is part of urllib3 and is released under
5
# the MIT License: http://www.opensource.org/licenses/mit-license.php
8
from urllib.parse import urlencode
10
from urllib import urlencode
12
from .filepost import encode_multipart_formdata
15
__all__ = ['RequestMethods']
18
class RequestMethods(object):
20
Convenience mixin for classes who implement a :meth:`urlopen` method, such
21
as :class:`~urllib3.connectionpool.HTTPConnectionPool` and
22
:class:`~urllib3.poolmanager.PoolManager`.
24
Provides behavior for making common types of HTTP request methods and
25
decides which type of request field encoding to use.
29
:meth:`.request_encode_url` is for sending requests whose fields are encoded
30
in the URL (such as GET, HEAD, DELETE).
32
:meth:`.request_encode_body` is for sending requests whose fields are
33
encoded in the *body* of the request using multipart or www-form-urlencoded
34
(such as for POST, PUT, PATCH).
36
:meth:`.request` is for making any kind of request, it will look up the
37
appropriate encoding format and use one of the above two methods to make
40
Initializer parameters:
43
Headers to include with all requests, unless other headers are given
47
_encode_url_methods = set(['DELETE', 'GET', 'HEAD', 'OPTIONS'])
49
def __init__(self, headers=None):
50
self.headers = headers or {}
52
def urlopen(self, method, url, body=None, headers=None,
53
encode_multipart=True, multipart_boundary=None,
55
raise NotImplemented("Classes extending RequestMethods must implement "
56
"their own ``urlopen`` method.")
58
def request(self, method, url, fields=None, headers=None, **urlopen_kw):
60
Make a request using :meth:`urlopen` with the appropriate encoding of
61
``fields`` based on the ``method`` used.
63
This is a convenience method that requires the least amount of manual
64
effort. It can be used in most situations, while still having the option
65
to drop down to more specific methods when necessary, such as
66
:meth:`request_encode_url`, :meth:`request_encode_body`,
67
or even the lowest level :meth:`urlopen`.
69
method = method.upper()
71
if method in self._encode_url_methods:
72
return self.request_encode_url(method, url, fields=fields,
76
return self.request_encode_body(method, url, fields=fields,
80
def request_encode_url(self, method, url, fields=None, **urlopen_kw):
82
Make a request using :meth:`urlopen` with the ``fields`` encoded in
83
the url. This is useful for request methods like GET, HEAD, DELETE, etc.
86
url += '?' + urlencode(fields)
87
return self.urlopen(method, url, **urlopen_kw)
89
def request_encode_body(self, method, url, fields=None, headers=None,
90
encode_multipart=True, multipart_boundary=None,
93
Make a request using :meth:`urlopen` with the ``fields`` encoded in
94
the body. This is useful for request methods like POST, PUT, PATCH, etc.
96
When ``encode_multipart=True`` (default), then
97
:meth:`urllib3.filepost.encode_multipart_formdata` is used to encode the
98
payload with the appropriate content type. Otherwise
99
:meth:`urllib.urlencode` is used with the
100
'application/x-www-form-urlencoded' content type.
102
Multipart encoding must be used when posting files, and it's reasonably
103
safe to use it in other times too. However, it may break request signing,
106
Supports an optional ``fields`` parameter of key/value strings AND
107
key/filetuple. A filetuple is a (filename, data, MIME type) tuple where
108
the MIME type is optional. For example: ::
112
'fakefile': ('foofile.txt', 'contents of foofile'),
113
'realfile': ('barfile.txt', open('realfile').read()),
114
'typedfile': ('bazfile.bin', open('bazfile').read(),
116
'nonamefile': 'contents of nonamefile field',
119
When uploading a file, providing a filename (the first parameter of the
120
tuple) is optional but recommended to best mimick behavior of browsers.
122
Note that if ``headers`` are supplied, the 'Content-Type' header will be
123
overwritten because it depends on the dynamic random boundary string
124
which is used to compose the body of the request. The random boundary
125
string can be explicitly set with the ``multipart_boundary`` parameter.
128
body, content_type = encode_multipart_formdata(fields or {},
129
boundary=multipart_boundary)
131
body, content_type = (urlencode(fields or {}),
132
'application/x-www-form-urlencoded')
135
headers = self.headers
137
headers_ = {'Content-Type': content_type}
138
headers_.update(headers)
140
return self.urlopen(method, url, body=body, headers=headers_,