Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

try: 

    from urllib.parse import urlencode 

except ImportError: 

    from urllib import urlencode 

 

from .filepost import encode_multipart_formdata 

 

 

__all__ = ['RequestMethods'] 

 

 

class RequestMethods(object): 

    """ 

    Convenience mixin for classes who implement a :meth:`urlopen` method, such 

    as :class:`~urllib3.connectionpool.HTTPConnectionPool` and 

    :class:`~urllib3.poolmanager.PoolManager`. 

 

    Provides behavior for making common types of HTTP request methods and 

    decides which type of request field encoding to use. 

 

    Specifically, 

 

    :meth:`.request_encode_url` is for sending requests whose fields are 

    encoded in the URL (such as GET, HEAD, DELETE). 

 

    :meth:`.request_encode_body` is for sending requests whose fields are 

    encoded in the *body* of the request using multipart or www-form-urlencoded 

    (such as for POST, PUT, PATCH). 

 

    :meth:`.request` is for making any kind of request, it will look up the 

    appropriate encoding format and use one of the above two methods to make 

    the request. 

 

    Initializer parameters: 

 

    :param headers: 

        Headers to include with all requests, unless other headers are given 

        explicitly. 

    """ 

 

    _encode_url_methods = set(['DELETE', 'GET', 'HEAD', 'OPTIONS']) 

 

    def __init__(self, headers=None): 

        self.headers = headers or {} 

 

    def urlopen(self, method, url, body=None, headers=None, 

                encode_multipart=True, multipart_boundary=None, 

                **kw):  # Abstract 

        raise NotImplemented("Classes extending RequestMethods must implement " 

                             "their own ``urlopen`` method.") 

 

    def request(self, method, url, fields=None, headers=None, **urlopen_kw): 

        """ 

        Make a request using :meth:`urlopen` with the appropriate encoding of 

        ``fields`` based on the ``method`` used. 

 

        This is a convenience method that requires the least amount of manual 

        effort. It can be used in most situations, while still having the 

        option to drop down to more specific methods when necessary, such as 

        :meth:`request_encode_url`, :meth:`request_encode_body`, 

        or even the lowest level :meth:`urlopen`. 

        """ 

        method = method.upper() 

 

        if method in self._encode_url_methods: 

            return self.request_encode_url(method, url, fields=fields, 

                                           headers=headers, 

                                           **urlopen_kw) 

        else: 

            return self.request_encode_body(method, url, fields=fields, 

                                            headers=headers, 

                                            **urlopen_kw) 

 

    def request_encode_url(self, method, url, fields=None, **urlopen_kw): 

        """ 

        Make a request using :meth:`urlopen` with the ``fields`` encoded in 

        the url. This is useful for request methods like GET, HEAD, DELETE, etc. 

        """ 

        if fields: 

            url += '?' + urlencode(fields) 

        return self.urlopen(method, url, **urlopen_kw) 

 

    def request_encode_body(self, method, url, fields=None, headers=None, 

                            encode_multipart=True, multipart_boundary=None, 

                            **urlopen_kw): 

        """ 

        Make a request using :meth:`urlopen` with the ``fields`` encoded in 

        the body. This is useful for request methods like POST, PUT, PATCH, etc. 

 

        When ``encode_multipart=True`` (default), then 

        :meth:`urllib3.filepost.encode_multipart_formdata` is used to encode 

        the payload with the appropriate content type. Otherwise 

        :meth:`urllib.urlencode` is used with the 

        'application/x-www-form-urlencoded' content type. 

 

        Multipart encoding must be used when posting files, and it's reasonably 

        safe to use it in other times too. However, it may break request 

        signing, such as with OAuth. 

 

        Supports an optional ``fields`` parameter of key/value strings AND 

        key/filetuple. A filetuple is a (filename, data, MIME type) tuple where 

        the MIME type is optional. For example:: 

 

            fields = { 

                'foo': 'bar', 

                'fakefile': ('foofile.txt', 'contents of foofile'), 

                'realfile': ('barfile.txt', open('realfile').read()), 

                'typedfile': ('bazfile.bin', open('bazfile').read(), 

                              'image/jpeg'), 

                'nonamefile': 'contents of nonamefile field', 

            } 

 

        When uploading a file, providing a filename (the first parameter of the 

        tuple) is optional but recommended to best mimick behavior of browsers. 

 

        Note that if ``headers`` are supplied, the 'Content-Type' header will 

        be overwritten because it depends on the dynamic random boundary string 

        which is used to compose the body of the request. The random boundary 

        string can be explicitly set with the ``multipart_boundary`` parameter. 

        """ 

        if headers is None: 

            headers = self.headers 

 

        extra_kw = {'headers': {}} 

 

        if fields: 

            if 'body' in urlopen_kw: 

                raise TypeError('request got values for both \'fields\' and \'body\', can only specify one.') 

 

            if encode_multipart: 

                body, content_type = encode_multipart_formdata(fields, boundary=multipart_boundary) 

            else: 

                body, content_type = urlencode(fields), 'application/x-www-form-urlencoded' 

 

            extra_kw['body'] = body 

            extra_kw['headers'] = {'Content-Type': content_type} 

 

        extra_kw['headers'].update(headers) 

        extra_kw.update(urlopen_kw) 

 

        return self.urlopen(method, url, **extra_kw)