Blame - Doc/library/http.client.rst - platform/external/python/cpython3

2008-05-26 16:32:26 +0000

[diff] [blame]

1

:mod:`http.client` --- HTTP protocol client

2

===========================================

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

3

Georg Brandl

2008-05-26 16:32:26 +0000

[diff] [blame]

4

.. module:: http.client

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

5

:synopsis: HTTP and HTTPS protocol client (requires sockets).

.. index::

pair: HTTP; protocol

Georg Brandl

2008-05-26 16:32:26 +0000

[diff] [blame]

10

single: HTTP; http.client (standard module)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

11

Senthil Kumaran

aca8fd7

2008-06-23 04:41:59 +0000

[diff] [blame]

12

.. index:: module: urllib.request

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

13

Raymond Hettinger

469271d

2011-01-27 20:38:46 +0000

[diff] [blame]

14

**Source code:** :source:`Lib/http/client.py`

--------------

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

18

This module defines classes which implement the client side of the HTTP and

Senthil Kumaran

aca8fd7

2008-06-23 04:41:59 +0000

[diff] [blame]

19

HTTPS protocols. It is normally not used directly --- the module

Georg Brandl

0f7ede4

2008-06-23 11:23:31 +0000

[diff] [blame]

20

:mod:`urllib.request` uses it to handle URLs that use HTTP and HTTPS.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

.. note::

Antoine Pitrou

2010-10-13 10:39:21 +0000

[diff] [blame]

24

HTTPS support is only available if Python was compiled with SSL support

25

(through the :mod:`ssl` module).

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

26

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

27

The module provides the following classes:

28

29

Senthil Kumaran

052ddb0

2013-03-18 14:11:41 -0700

[diff] [blame]

30

.. class:: HTTPConnection(host, port=None[, timeout], \

Ezio Melotti

e0add76

2012-09-14 06:32:35 +0300

[diff] [blame]

31

source_address=None)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

32

33

An :class:`HTTPConnection` instance represents one transaction with an HTTP

Alexandre Vassalotti

5f8ced2

2008-05-16 00:03:33 +0000

[diff] [blame]

34

server. It should be instantiated passing it a host and optional port

35

number. If no port number is passed, the port is extracted from the host

36

string if it has the form ``host:port``, else the default HTTP port (80) is

Antoine Pitrou

988dbd7

2010-12-17 17:35:56 +0000

[diff] [blame]

37

used. If the optional *timeout* parameter is given, blocking

Alexandre Vassalotti

5f8ced2

2008-05-16 00:03:33 +0000

[diff] [blame]

38

operations (like connection attempts) will timeout after that many seconds

Georg Brandl

f78e02b

2008-06-10 17:40:04 +0000

[diff] [blame]

39

(if it is not given, the global default timeout setting is used).

Raymond Hettinger

519c308

2011-01-30 00:39:00 +0000

[diff] [blame]

40

The optional *source_address* parameter may be a tuple of a (host, port)

Gregory P. Smith

2010-01-03 03:28:29 +0000

[diff] [blame]

41

to use as the source address the HTTP connection is made from.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

42

43

For example, the following calls all create instances that connect to the server

44

at the same host and port::

45

Georg Brandl

2008-05-26 16:32:26 +0000

[diff] [blame]

46

>>> h1 = http.client.HTTPConnection('www.cwi.nl')

47

>>> h2 = http.client.HTTPConnection('www.cwi.nl:80')

48

>>> h3 = http.client.HTTPConnection('www.cwi.nl', 80)

49

>>> h3 = http.client.HTTPConnection('www.cwi.nl', 80, timeout=10)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

50

Gregory P. Smith

2010-01-03 03:28:29 +0000

[diff] [blame]

51

.. versionchanged:: 3.2

52

*source_address* was added.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

53

Senthil Kumaran

aced69f

2013-03-19 01:22:56 -0700

[diff] [blame]

54

.. versionchanged:: 3.4

55

The *strict* parameter is removed. HTTP 0.9-style "Simple Responses" are

56

not supported.

Gregory P. Smith

2010-01-03 03:28:29 +0000

[diff] [blame]

57

Antoine Pitrou

988dbd7

2010-12-17 17:35:56 +0000

[diff] [blame]

58

Ezio Melotti

e0add76

2012-09-14 06:32:35 +0300

[diff] [blame]

59

.. class:: HTTPSConnection(host, port=None, key_file=None, \

Senthil Kumaran

052ddb0

2013-03-18 14:11:41 -0700

[diff] [blame]

60

cert_file=None[, timeout], \

Ezio Melotti

e0add76

2012-09-14 06:32:35 +0300

[diff] [blame]

61

source_address=None, *, context=None, \

62

check_hostname=None)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

63

64

A subclass of :class:`HTTPConnection` that uses SSL for communication with

Antoine Pitrou

803e6d6

2010-10-13 10:36:15 +0000

[diff] [blame]

65

secure servers. Default port is ``443``. If *context* is specified, it

66

must be a :class:`ssl.SSLContext` instance describing the various SSL

67

options. If *context* is specified and has a :attr:`~ssl.SSLContext.verify_mode`

68

of either :data:`~ssl.CERT_OPTIONAL` or :data:`~ssl.CERT_REQUIRED`, then

69

by default *host* is matched against the host name(s) allowed by the

70

server's certificate. If you want to change that behaviour, you can

71

explicitly set *check_hostname* to False.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

72

Antoine Pitrou

803e6d6

2010-10-13 10:36:15 +0000

[diff] [blame]

73

*key_file* and *cert_file* are deprecated, please use

74

:meth:`ssl.SSLContext.load_cert_chain` instead.

75

76

If you access arbitrary hosts on the Internet, it is recommended to

77

require certificate checking and feed the *context* with a set of

78

trusted CA certificates::

79

80

context = ssl.SSLContext(ssl.PROTOCOL_TLSv1)

81

context.verify_mode = ssl.CERT_REQUIRED

82

context.load_verify_locations('/etc/pki/tls/certs/ca-bundle.crt')

83

h = client.HTTPSConnection('svn.python.org', 443, context=context)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

84

Gregory P. Smith

2010-01-03 03:28:29 +0000

[diff] [blame]

85

.. versionchanged:: 3.2

Antoine Pitrou

803e6d6

2010-10-13 10:36:15 +0000

[diff] [blame]

86

*source_address*, *context* and *check_hostname* were added.

Gregory P. Smith

2010-01-03 03:28:29 +0000

[diff] [blame]

87

Antoine Pitrou

d532321

2010-10-22 18:19:07 +0000

[diff] [blame]

88

.. versionchanged:: 3.2

89

This class now supports HTTPS virtual hosts if possible (that is,

90

if :data:`ssl.HAS_SNI` is true).

91

Senthil Kumaran

aced69f

2013-03-19 01:22:56 -0700

[diff] [blame]

92

.. versionchanged:: 3.4

93

The *strict* parameter is removed. HTTP 0.9-style "Simple Responses" are

94

not supported anymore.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

95

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

96

Senthil Kumaran

052ddb0

2013-03-18 14:11:41 -0700

[diff] [blame]

97

.. class:: HTTPResponse(sock, debuglevel=0, method=None, url=None)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

98

Jeremy Hylton

2009-03-31 14:40:19 +0000

[diff] [blame]

99

Class whose instances are returned upon successful connection. Not

100

instantiated directly by user.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

101

Senthil Kumaran

aced69f

2013-03-19 01:22:56 -0700

[diff] [blame]

102

.. versionchanged:: 3.4

103

The *strict* parameter is removed. HTTP 0.9 style "Simple Responses" are

104

not supported anymore.

Antoine Pitrou

988dbd7

2010-12-17 17:35:56 +0000

[diff] [blame]

105

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

106

107

The following exceptions are raised as appropriate:

108

109

110

.. exception:: HTTPException

111

112

The base class of the other exceptions in this module. It is a subclass of

113

:exc:`Exception`.

114

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

115

116

.. exception:: NotConnected

117

118

A subclass of :exc:`HTTPException`.

119

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

120

121

.. exception:: InvalidURL

122

123

A subclass of :exc:`HTTPException`, raised if a port is given and is either

124

non-numeric or empty.

125

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

126

127

.. exception:: UnknownProtocol

128

129

A subclass of :exc:`HTTPException`.

130

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

131

132

.. exception:: UnknownTransferEncoding

133

134

A subclass of :exc:`HTTPException`.

135

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

136

137

.. exception:: UnimplementedFileMode

138

139

A subclass of :exc:`HTTPException`.

140

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

141

142

.. exception:: IncompleteRead

143

144

A subclass of :exc:`HTTPException`.

145

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

146

147

.. exception:: ImproperConnectionState

148

149

A subclass of :exc:`HTTPException`.

150

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

151

152

.. exception:: CannotSendRequest

153

154

A subclass of :exc:`ImproperConnectionState`.

155

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

156

157

.. exception:: CannotSendHeader

158

159

A subclass of :exc:`ImproperConnectionState`.

160

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

161

162

.. exception:: ResponseNotReady

163

164

A subclass of :exc:`ImproperConnectionState`.

165

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

166

167

.. exception:: BadStatusLine

168

169

A subclass of :exc:`HTTPException`. Raised if a server responds with a HTTP

170

status code that we don't understand.

171

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

172

The constants defined in this module are:

.. data:: HTTP_PORT

The default port for the HTTP protocol (always ``80``).

.. data:: HTTPS_PORT

The default port for the HTTPS protocol (always ``443``).

183

184

and also the following constants for integer status codes:

185

186

+------------------------------------------+---------+-----------------------------------------------------------------------+

187

| Constant | Value | Definition |

188

+==========================================+=========+=======================================================================+

189

| :const:`CONTINUE` | ``100`` | HTTP/1.1, `RFC 2616, Section |

190

| | | 10.1.1 |

191

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.1>`_ |

192

+------------------------------------------+---------+-----------------------------------------------------------------------+

193

| :const:`SWITCHING_PROTOCOLS` | ``101`` | HTTP/1.1, `RFC 2616, Section |

194

| | | 10.1.2 |

195

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.2>`_ |

196

+------------------------------------------+---------+-----------------------------------------------------------------------+

197

| :const:`PROCESSING` | ``102`` | WEBDAV, `RFC 2518, Section 10.1 |

198

| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_102>`_ |

199

+------------------------------------------+---------+-----------------------------------------------------------------------+

200

| :const:`OK` | ``200`` | HTTP/1.1, `RFC 2616, Section |

201

| | | 10.2.1 |

202

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1>`_ |

203

+------------------------------------------+---------+-----------------------------------------------------------------------+

204

| :const:`CREATED` | ``201`` | HTTP/1.1, `RFC 2616, Section |

205

| | | 10.2.2 |

206

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2>`_ |

207

+------------------------------------------+---------+-----------------------------------------------------------------------+

208

| :const:`ACCEPTED` | ``202`` | HTTP/1.1, `RFC 2616, Section |

209

| | | 10.2.3 |

210

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3>`_ |

211

+------------------------------------------+---------+-----------------------------------------------------------------------+

212

| :const:`NON_AUTHORITATIVE_INFORMATION` | ``203`` | HTTP/1.1, `RFC 2616, Section |

213

| | | 10.2.4 |

214

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.4>`_ |

215

+------------------------------------------+---------+-----------------------------------------------------------------------+

216

| :const:`NO_CONTENT` | ``204`` | HTTP/1.1, `RFC 2616, Section |

217

| | | 10.2.5 |

218

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5>`_ |

219

+------------------------------------------+---------+-----------------------------------------------------------------------+

220

| :const:`RESET_CONTENT` | ``205`` | HTTP/1.1, `RFC 2616, Section |

221

| | | 10.2.6 |

222

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.6>`_ |

223

+------------------------------------------+---------+-----------------------------------------------------------------------+

224

| :const:`PARTIAL_CONTENT` | ``206`` | HTTP/1.1, `RFC 2616, Section |

225

| | | 10.2.7 |

226

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7>`_ |

227

+------------------------------------------+---------+-----------------------------------------------------------------------+

228

| :const:`MULTI_STATUS` | ``207`` | WEBDAV `RFC 2518, Section 10.2 |

229

| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_207>`_ |

230

+------------------------------------------+---------+-----------------------------------------------------------------------+

231

| :const:`IM_USED` | ``226`` | Delta encoding in HTTP, |

232

| | | :rfc:`3229`, Section 10.4.1 |

233

+------------------------------------------+---------+-----------------------------------------------------------------------+

234

| :const:`MULTIPLE_CHOICES` | ``300`` | HTTP/1.1, `RFC 2616, Section |

235

| | | 10.3.1 |

236

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.1>`_ |

237

+------------------------------------------+---------+-----------------------------------------------------------------------+

238

| :const:`MOVED_PERMANENTLY` | ``301`` | HTTP/1.1, `RFC 2616, Section |

239

| | | 10.3.2 |

240

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2>`_ |

241

+------------------------------------------+---------+-----------------------------------------------------------------------+

242

| :const:`FOUND` | ``302`` | HTTP/1.1, `RFC 2616, Section |

243

| | | 10.3.3 |

244

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3>`_ |

245

+------------------------------------------+---------+-----------------------------------------------------------------------+

246

| :const:`SEE_OTHER` | ``303`` | HTTP/1.1, `RFC 2616, Section |

247

| | | 10.3.4 |

248

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4>`_ |

249

+------------------------------------------+---------+-----------------------------------------------------------------------+

250

| :const:`NOT_MODIFIED` | ``304`` | HTTP/1.1, `RFC 2616, Section |

251

| | | 10.3.5 |

252

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5>`_ |

253

+------------------------------------------+---------+-----------------------------------------------------------------------+

254

| :const:`USE_PROXY` | ``305`` | HTTP/1.1, `RFC 2616, Section |

255

| | | 10.3.6 |

256

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.6>`_ |

257

+------------------------------------------+---------+-----------------------------------------------------------------------+

258

| :const:`TEMPORARY_REDIRECT` | ``307`` | HTTP/1.1, `RFC 2616, Section |

259

| | | 10.3.8 |

260

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8>`_ |

261

+------------------------------------------+---------+-----------------------------------------------------------------------+

262

| :const:`BAD_REQUEST` | ``400`` | HTTP/1.1, `RFC 2616, Section |

263

| | | 10.4.1 |

264

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1>`_ |

265

+------------------------------------------+---------+-----------------------------------------------------------------------+

266

| :const:`UNAUTHORIZED` | ``401`` | HTTP/1.1, `RFC 2616, Section |

267

| | | 10.4.2 |

268

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2>`_ |

269

+------------------------------------------+---------+-----------------------------------------------------------------------+

270

| :const:`PAYMENT_REQUIRED` | ``402`` | HTTP/1.1, `RFC 2616, Section |

271

| | | 10.4.3 |

272

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3>`_ |

273

+------------------------------------------+---------+-----------------------------------------------------------------------+

274

| :const:`FORBIDDEN` | ``403`` | HTTP/1.1, `RFC 2616, Section |

275

| | | 10.4.4 |

276

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4>`_ |

277

+------------------------------------------+---------+-----------------------------------------------------------------------+

278

| :const:`NOT_FOUND` | ``404`` | HTTP/1.1, `RFC 2616, Section |

279

| | | 10.4.5 |

280

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5>`_ |

281

+------------------------------------------+---------+-----------------------------------------------------------------------+

282

| :const:`METHOD_NOT_ALLOWED` | ``405`` | HTTP/1.1, `RFC 2616, Section |

283

| | | 10.4.6 |

284

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6>`_ |

285

+------------------------------------------+---------+-----------------------------------------------------------------------+

286

| :const:`NOT_ACCEPTABLE` | ``406`` | HTTP/1.1, `RFC 2616, Section |

287

| | | 10.4.7 |

288

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7>`_ |

289

+------------------------------------------+---------+-----------------------------------------------------------------------+

290

| :const:`PROXY_AUTHENTICATION_REQUIRED` | ``407`` | HTTP/1.1, `RFC 2616, Section |

291

| | | 10.4.8 |

292

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.8>`_ |

293

+------------------------------------------+---------+-----------------------------------------------------------------------+

294

| :const:`REQUEST_TIMEOUT` | ``408`` | HTTP/1.1, `RFC 2616, Section |

295

| | | 10.4.9 |

296

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9>`_ |

297

+------------------------------------------+---------+-----------------------------------------------------------------------+

298

| :const:`CONFLICT` | ``409`` | HTTP/1.1, `RFC 2616, Section |

299

| | | 10.4.10 |

300

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10>`_ |

301

+------------------------------------------+---------+-----------------------------------------------------------------------+

302

| :const:`GONE` | ``410`` | HTTP/1.1, `RFC 2616, Section |

303

| | | 10.4.11 |

304

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11>`_ |

305

+------------------------------------------+---------+-----------------------------------------------------------------------+

306

| :const:`LENGTH_REQUIRED` | ``411`` | HTTP/1.1, `RFC 2616, Section |

307

| | | 10.4.12 |

308

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.12>`_ |

309

+------------------------------------------+---------+-----------------------------------------------------------------------+

310

| :const:`PRECONDITION_FAILED` | ``412`` | HTTP/1.1, `RFC 2616, Section |

311

| | | 10.4.13 |

312

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13>`_ |

313

+------------------------------------------+---------+-----------------------------------------------------------------------+

314

| :const:`REQUEST_ENTITY_TOO_LARGE` | ``413`` | HTTP/1.1, `RFC 2616, Section |

315

| | | 10.4.14 |

316

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14>`_ |

317

+------------------------------------------+---------+-----------------------------------------------------------------------+

318

| :const:`REQUEST_URI_TOO_LONG` | ``414`` | HTTP/1.1, `RFC 2616, Section |

319

| | | 10.4.15 |

320

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.15>`_ |

321

+------------------------------------------+---------+-----------------------------------------------------------------------+

322

| :const:`UNSUPPORTED_MEDIA_TYPE` | ``415`` | HTTP/1.1, `RFC 2616, Section |

323

| | | 10.4.16 |

324

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16>`_ |

325

+------------------------------------------+---------+-----------------------------------------------------------------------+

326

| :const:`REQUESTED_RANGE_NOT_SATISFIABLE` | ``416`` | HTTP/1.1, `RFC 2616, Section |

327

| | | 10.4.17 |

328

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.17>`_ |

329

+------------------------------------------+---------+-----------------------------------------------------------------------+

330

| :const:`EXPECTATION_FAILED` | ``417`` | HTTP/1.1, `RFC 2616, Section |

331

| | | 10.4.18 |

332

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.18>`_ |

333

+------------------------------------------+---------+-----------------------------------------------------------------------+

334

| :const:`UNPROCESSABLE_ENTITY` | ``422`` | WEBDAV, `RFC 2518, Section 10.3 |

335

| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_422>`_ |

336

+------------------------------------------+---------+-----------------------------------------------------------------------+

337

| :const:`LOCKED` | ``423`` | WEBDAV `RFC 2518, Section 10.4 |

338

| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_423>`_ |

339

+------------------------------------------+---------+-----------------------------------------------------------------------+

340

| :const:`FAILED_DEPENDENCY` | ``424`` | WEBDAV, `RFC 2518, Section 10.5 |

341

| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_424>`_ |

342

+------------------------------------------+---------+-----------------------------------------------------------------------+

343

| :const:`UPGRADE_REQUIRED` | ``426`` | HTTP Upgrade to TLS, |

344

| | | :rfc:`2817`, Section 6 |

345

+------------------------------------------+---------+-----------------------------------------------------------------------+

Hynek Schlawack

51b2ed5

2012-05-16 09:51:07 +0200

[diff] [blame]

346

| :const:`PRECONDITION_REQUIRED` | ``428`` | Additional HTTP Status Codes, |

347

| | | :rfc:`6585`, Section 3 |

348

+------------------------------------------+---------+-----------------------------------------------------------------------+

349

| :const:`TOO_MANY_REQUESTS` | ``429`` | Additional HTTP Status Codes, |

350

| | | :rfc:`6585`, Section 4 |

351

+------------------------------------------+---------+-----------------------------------------------------------------------+

352

| :const:`REQUEST_HEADER_FIELDS_TOO_LARGE` | ``431`` | Additional HTTP Status Codes, |

353

| | | :rfc:`6585`, Section 5 |

354

+------------------------------------------+---------+-----------------------------------------------------------------------+

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

355

| :const:`INTERNAL_SERVER_ERROR` | ``500`` | HTTP/1.1, `RFC 2616, Section |

356

| | | 10.5.1 |

357

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1>`_ |

358

+------------------------------------------+---------+-----------------------------------------------------------------------+

359

| :const:`NOT_IMPLEMENTED` | ``501`` | HTTP/1.1, `RFC 2616, Section |

360

| | | 10.5.2 |

361

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2>`_ |

362

+------------------------------------------+---------+-----------------------------------------------------------------------+

363

| :const:`BAD_GATEWAY` | ``502`` | HTTP/1.1 `RFC 2616, Section |

364

| | | 10.5.3 |

365

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3>`_ |

366

+------------------------------------------+---------+-----------------------------------------------------------------------+

367

| :const:`SERVICE_UNAVAILABLE` | ``503`` | HTTP/1.1, `RFC 2616, Section |

368

| | | 10.5.4 |

369

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4>`_ |

370

+------------------------------------------+---------+-----------------------------------------------------------------------+

371

| :const:`GATEWAY_TIMEOUT` | ``504`` | HTTP/1.1 `RFC 2616, Section |

372

| | | 10.5.5 |

373

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5>`_ |

374

+------------------------------------------+---------+-----------------------------------------------------------------------+

375

| :const:`HTTP_VERSION_NOT_SUPPORTED` | ``505`` | HTTP/1.1, `RFC 2616, Section |

376

| | | 10.5.6 |

377

| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.6>`_ |

378

+------------------------------------------+---------+-----------------------------------------------------------------------+

379

| :const:`INSUFFICIENT_STORAGE` | ``507`` | WEBDAV, `RFC 2518, Section 10.6 |

380

| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_507>`_ |

381

+------------------------------------------+---------+-----------------------------------------------------------------------+

382

| :const:`NOT_EXTENDED` | ``510`` | An HTTP Extension Framework, |

383

| | | :rfc:`2774`, Section 7 |

384

+------------------------------------------+---------+-----------------------------------------------------------------------+

Hynek Schlawack

51b2ed5

2012-05-16 09:51:07 +0200

[diff] [blame]

385

| :const:`NETWORK_AUTHENTICATION_REQUIRED` | ``511`` | Additional HTTP Status Codes, |

386

| | | :rfc:`6585`, Section 6 |

387

+------------------------------------------+---------+-----------------------------------------------------------------------+

388

Georg Brandl

945a3ad

2012-05-21 20:28:58 +0200

[diff] [blame]

389

.. versionchanged:: 3.3

390

Added codes ``428``, ``429``, ``431`` and ``511`` from :rfc:`6585`.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

.. data:: responses

This dictionary maps the HTTP 1.1 status codes to the W3C names.

396

Georg Brandl

2008-05-26 16:32:26 +0000

[diff] [blame]

397

Example: ``http.client.responses[http.client.NOT_FOUND]`` is ``'Not Found'``.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

398

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

399

400

.. _httpconnection-objects:

401

402

HTTPConnection Objects

403

----------------------

404

405

:class:`HTTPConnection` instances have the following methods:

406

407

Georg Brandl

036490d

2009-05-17 13:00:36 +0000

[diff] [blame]

408

.. method:: HTTPConnection.request(method, url, body=None, headers={})

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

409

Jeremy Hylton

236654b

2009-03-27 20:24:34 +0000

[diff] [blame]

410

This will send a request to the server using the HTTP request

411

method *method* and the selector *url*. If the *body* argument is

412

present, it should be string or bytes object of data to send after

413

the headers are finished. Strings are encoded as ISO-8859-1, the

414

default charset for HTTP. To use other encodings, pass a bytes

415

object. The Content-Length header is set to the length of the

416

string.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

417

Antoine Pitrou

11cb961

2010-09-15 11:11:28 +0000

[diff] [blame]

418

The *body* may also be an open :term:`file object`, in which case the

Senthil Kumaran

2010-12-19 10:49:52 +0000

[diff] [blame]

419

contents of the file is sent; this file object should support ``fileno()``

420

and ``read()`` methods. The header Content-Length is automatically set to

421

the length of the file as reported by stat. The *body* argument may also be

Raymond Hettinger

519c308

2011-01-30 00:39:00 +0000

[diff] [blame]

422

an iterable and Content-Length header should be explicitly provided when the

Senthil Kumaran

2010-12-19 10:49:52 +0000

[diff] [blame]

423

body is an iterable.

Jeremy Hylton

236654b

2009-03-27 20:24:34 +0000

[diff] [blame]

424

425

The *headers* argument should be a mapping of extra HTTP

426

headers to send with the request.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

427

Senthil Kumaran

2010-12-19 10:49:52 +0000

[diff] [blame]

428

.. versionadded:: 3.2

Georg Brandl

09a7df8

2010-12-19 12:33:52 +0000

[diff] [blame]

429

*body* can now be an iterable.

Senthil Kumaran

2010-12-19 10:49:52 +0000

[diff] [blame]

430

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

431

.. method:: HTTPConnection.getresponse()

432

433

Should be called after a request is sent to get the response from the server.

434

Returns an :class:`HTTPResponse` instance.

.. note::

Note that you must have read the whole response before you can send a new

439

request to the server.

440

441

442

.. method:: HTTPConnection.set_debuglevel(level)

443

R. David Murray

d89bc3f

2010-12-15 02:19:14 +0000

[diff] [blame]

444

Set the debugging level. The default debug level is ``0``, meaning no

445

debugging output is printed. Any value greater than ``0`` will cause all

446

currently defined debug output to be printed to stdout. The ``debuglevel``

447

is passed to any new :class:`HTTPResponse` objects that are created.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

448

Mark Dickinson

574b1d6

2009-10-01 20:20:09 +0000

[diff] [blame]

449

.. versionadded:: 3.1

Benjamin Peterson

fa0d703

2009-06-01 22:42:33 +0000

[diff] [blame]

450

Georg Brandl

67b21b7

2010-08-17 15:07:14 +0000

[diff] [blame]

451

Senthil Kumaran

7e5229c

2009-12-20 07:31:21 +0000

[diff] [blame]

452

.. method:: HTTPConnection.set_tunnel(host, port=None, headers=None)

Senthil Kumaran

97f0c6b

2009-07-25 04:24:38 +0000

[diff] [blame]

453

454

Set the host and the port for HTTP Connect Tunnelling. Normally used when it

455

is required to a HTTPS Connection through a proxy server.

456

Sandro Tosi

44f568c

2011-12-25 11:44:38 +0100

[diff] [blame]

457

The headers argument should be a mapping of extra HTTP headers to send

Senthil Kumaran

7e5229c

2009-12-20 07:31:21 +0000

[diff] [blame]

458

with the CONNECT request.

459

Senthil Kumaran

2e910fd

2009-07-25 04:27:38 +0000

[diff] [blame]

460

.. versionadded:: 3.2

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

461

Georg Brandl

67b21b7

2010-08-17 15:07:14 +0000

[diff] [blame]

462

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

463

.. method:: HTTPConnection.connect()

464

465

Connect to the server specified when the object was created.

466

467

468

.. method:: HTTPConnection.close()

469

470

Close the connection to the server.

471

472

As an alternative to using the :meth:`request` method described above, you can

473

also send your request step by step, by using the four functions below.

474

475

Georg Brandl

036490d

2009-05-17 13:00:36 +0000

[diff] [blame]

476

.. method:: HTTPConnection.putrequest(request, selector, skip_host=False, skip_accept_encoding=False)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

477

478

This should be the first call after the connection to the server has been made.

479

It sends a line to the server consisting of the *request* string, the *selector*

480

string, and the HTTP version (``HTTP/1.1``). To disable automatic sending of

481

``Host:`` or ``Accept-Encoding:`` headers (for example to accept additional

482

content encodings), specify *skip_host* or *skip_accept_encoding* with non-False

483

values.

484

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

485

486

.. method:: HTTPConnection.putheader(header, argument[, ...])

487

488

Send an :rfc:`822`\ -style header to the server. It sends a line to the server

489

consisting of the header, a colon and a space, and the first argument. If more

490

arguments are given, continuation lines are sent, each consisting of a tab and

an argument.

Senthil Kumaran

2011-10-03 07:27:06 +0800

[diff] [blame]

494

.. method:: HTTPConnection.endheaders(message_body=None)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

495

Senthil Kumaran

5d0de3f

2011-10-03 07:27:06 +0800

[diff] [blame]

496

Send a blank line to the server, signalling the end of the headers. The

Senthil Kumaran

ad87fa6

2011-10-05 23:26:49 +0800

[diff] [blame]

497

optional *message_body* argument can be used to pass a message body

498

associated with the request. The message body will be sent in the same

499

packet as the message headers if it is string, otherwise it is sent in a

500

separate packet.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

501

502

.. method:: HTTPConnection.send(data)

503

504

Send data to the server. This should be used directly only after the

505

:meth:`endheaders` method has been called and before :meth:`getresponse` is

called.

.. _httpresponse-objects:

HTTPResponse Objects

--------------------

Jeremy Hylton

2009-03-31 14:40:19 +0000

[diff] [blame]

514

An :class:`HTTPResponse` instance wraps the HTTP response from the

515

server. It provides access to the request headers and the entity

516

body. The response is an iterable object and can be used in a with

517

statement.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

518

519

520

.. method:: HTTPResponse.read([amt])

521

522

Reads and returns the response body, or up to the next *amt* bytes.

523

Antoine Pitrou

38d9643

2011-12-06 22:33:57 +0100

[diff] [blame]

524

.. method:: HTTPResponse.readinto(b)

525

526

Reads up to the next len(b) bytes of the response body into the buffer *b*.

527

Returns the number of bytes read.

528

529

.. versionadded:: 3.3

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

530

Georg Brandl

036490d

2009-05-17 13:00:36 +0000

[diff] [blame]

531

.. method:: HTTPResponse.getheader(name, default=None)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

532

Senthil Kumaran

790f831

2010-08-02 17:09:02 +0000

[diff] [blame]

533

Return the value of the header *name*, or *default* if there is no header

534

matching *name*. If there is more than one header with the name *name*,

535

return all of the values joined by ', '. If 'default' is any iterable other

536

than a single string, its elements are similarly returned joined by commas.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

537

538

539

.. method:: HTTPResponse.getheaders()

540

541

Return a list of (header, value) tuples.

542

Senthil Kumaran

ceff566

2010-09-21 01:57:43 +0000

[diff] [blame]

543

.. method:: HTTPResponse.fileno()

544

545

Return the ``fileno`` of the underlying socket.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

546

547

.. attribute:: HTTPResponse.msg

548

Jeremy Hylton

2009-03-31 14:40:19 +0000

[diff] [blame]

549

A :class:`http.client.HTTPMessage` instance containing the response

550

headers. :class:`http.client.HTTPMessage` is a subclass of

551

:class:`email.message.Message`.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

552

553

554

.. attribute:: HTTPResponse.version

555

556

HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.

557

558

559

.. attribute:: HTTPResponse.status

560

561

Status code returned by server.

562

563

564

.. attribute:: HTTPResponse.reason

565

566

Reason phrase returned by server.

567

568

Jeremy Hylton

2009-03-31 14:40:19 +0000

[diff] [blame]

569

.. attribute:: HTTPResponse.debuglevel

570

Georg Brandl

ef871f6

2010-03-12 10:06:40 +0000

[diff] [blame]

571

A debugging hook. If :attr:`debuglevel` is greater than zero, messages

Jeremy Hylton

2009-03-31 14:40:19 +0000

[diff] [blame]

572

will be printed to stdout as the response is read and parsed.

573

Senthil Kumaran

ce9b596

2011-06-19 16:56:49 -0700

[diff] [blame]

574

.. attribute:: HTTPResponse.closed

575

Senthil Kumaran

fd8d7e9

2011-06-19 16:59:41 -0700

[diff] [blame]

576

Is True if the stream is closed.

Jeremy Hylton

2009-03-31 14:40:19 +0000

[diff] [blame]

577

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

Examples

--------

Here is an example session that uses the ``GET`` method::

582

Georg Brandl

2008-05-26 16:32:26 +0000

[diff] [blame]

583

>>> import http.client

584

>>> conn = http.client.HTTPConnection("www.python.org")

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

585

>>> conn.request("GET", "/index.html")

586

>>> r1 = conn.getresponse()

Georg Brandl

6911e3c

2007-09-04 07:15:32 +0000

[diff] [blame]

587

>>> print(r1.status, r1.reason)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

588

200 OK

Senthil Kumaran

ce9b596

2011-06-19 16:56:49 -0700

[diff] [blame]

589

>>> data1 = r1.read() # This will return entire content.

590

>>> # The following example demonstrates reading data in chunks.

591

>>> conn.request("GET", "/index.html")

592

>>> r1 = conn.getresponse()

593

>>> while not r1.closed:

594

... print(r1.read(200)) # 200 bytes

595

b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"...

596

...

597

>>> # Example of an invalid request

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

598

>>> conn.request("GET", "/parrot.spam")

599

>>> r2 = conn.getresponse()

Georg Brandl

6911e3c

2007-09-04 07:15:32 +0000

[diff] [blame]

600

>>> print(r2.status, r2.reason)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

601

404 Not Found

602

>>> data2 = r2.read()

603

>>> conn.close()

604

Fred Drake

1587e3d

2010-05-12 01:36:11 +0000

[diff] [blame]

605

Here is an example session that uses the ``HEAD`` method. Note that the

606

``HEAD`` method never returns any data. ::

Senthil Kumaran

71fb6c8

2010-04-28 17:39:48 +0000

[diff] [blame]

607

608

>>> import http.client

609

>>> conn = http.client.HTTPConnection("www.python.org")

610

>>> conn.request("HEAD","/index.html")

611

>>> res = conn.getresponse()

612

>>> print(res.status, res.reason)

613

200 OK

614

>>> data = res.read()

>>> print(len(data))

0

>>> data == b''

True

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

620

Here is an example session that shows how to ``POST`` requests::

621

Senthil Kumaran

aca8fd7

2008-06-23 04:41:59 +0000

[diff] [blame]

622

>>> import http.client, urllib.parse

Senthil Kumaran

2011-07-20 21:56:24 +0800

[diff] [blame]

623

>>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

624

>>> headers = {"Content-type": "application/x-www-form-urlencoded",

625

... "Accept": "text/plain"}

Senthil Kumaran

2011-07-20 21:56:24 +0800

[diff] [blame]

626

>>> conn = http.client.HTTPConnection("bugs.python.org")

627

>>> conn.request("POST", "", params, headers)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

628

>>> response = conn.getresponse()

Georg Brandl

6911e3c

2007-09-04 07:15:32 +0000

[diff] [blame]

629

>>> print(response.status, response.reason)

Senthil Kumaran

2011-07-20 21:56:24 +0800

[diff] [blame]

630

302 Found

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

631

>>> data = response.read()

Senthil Kumaran

2011-07-20 21:56:24 +0800

[diff] [blame]

632

>>> data

633

b'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

634

>>> conn.close()

635

Senthil Kumaran

b5fe247

2013-03-13 13:38:33 -0700

[diff] [blame]

636

Client side ``HTTP PUT`` requests are very similar to ``POST`` requests. The

637

difference lies only the server side where HTTP server will allow resources to

Senthil Kumaran

e66cc81

2013-03-13 13:42:47 -0700

[diff] [blame]

638

be created via ``PUT`` request. It should be noted that custom HTTP methods

639

+are also handled in :class:`urllib.request.Request` by sending the appropriate

640

+method attribute.Here is an example session that shows how to do ``PUT``

641

request using http.client::

Senthil Kumaran

b5fe247

2013-03-13 13:38:33 -0700

[diff] [blame]

642

643

>>> # This creates an HTTP message

644

>>> # with the content of BODY as the enclosed representation

645

>>> # for the resource http://localhost:8080/foobar

646

...

647

>>> import http.client

648

>>> BODY = "***filecontents***"

649

>>> conn = http.client.HTTPConnection("localhost", 8080)

650

>>> conn.request("PUT", "/file", BODY)

651

>>> response = conn.getresponse()

652

>>> print(resp.status, response.reason)

653

200, OK

Jeremy Hylton

2009-03-31 14:40:19 +0000

[diff] [blame]

654

655

.. _httpmessage-objects:

HTTPMessage Objects

-------------------

Benjamin Peterson

2009-04-02 00:24:00 +0000

[diff] [blame]

660

An :class:`http.client.HTTPMessage` instance holds the headers from an HTTP

661

response. It is implemented using the :class:`email.message.Message` class.

Jeremy Hylton