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

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

Ezio Melotti

e0add76

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

[diff] [blame^]

30

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

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

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

Antoine Pitrou

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

[diff] [blame]

54

.. versionchanged:: 3.2

55

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

56

are not supported anymore.

Gregory P. Smith

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

[diff] [blame]

57

Antoine Pitrou

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, \

60

cert_file=None[, strict][, timeout], \

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

Antoine Pitrou

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

[diff] [blame]

92

.. versionchanged:: 3.2

93

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

94

are not supported anymore.

Georg Brandl

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

[diff] [blame]

95

Antoine Pitrou

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

[diff] [blame]

96

97

.. class:: HTTPResponse(sock, debuglevel=0[, strict], 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

Antoine Pitrou

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

[diff] [blame]

102

.. versionchanged:: 3.2

103

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

104

are not supported anymore.

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

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

346

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

347

| | | 10.5.1 |

348

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

349

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

350

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

351

| | | 10.5.2 |

352

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

353

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

354

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

355

| | | 10.5.3 |

356

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

357

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

358

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

359

| | | 10.5.4 |

360

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

361

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

362

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

363

| | | 10.5.5 |

364

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

365

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

366

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

367

| | | 10.5.6 |

368

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

369

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

370

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

371

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

372

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

373

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

374

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

375

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

.. data:: responses

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

381

Georg Brandl

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

[diff] [blame]

382

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

Georg Brandl

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

[diff] [blame]

383

Georg Brandl

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

[diff] [blame]

384

385

.. _httpconnection-objects:

386

387

HTTPConnection Objects

388

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

389

390

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

391

392

Georg Brandl

036490d

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

[diff] [blame]

393

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

Georg Brandl

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

[diff] [blame]

394

Jeremy Hylton

236654b

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

[diff] [blame]

395

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

396

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

397

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

398

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

399

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

400

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

401

string.

Georg Brandl

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

[diff] [blame]

402

Antoine Pitrou

11cb961

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

[diff] [blame]

403

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]

404

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

405

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

406

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]

407

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

Senthil Kumaran

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

[diff] [blame]

408

body is an iterable.

Jeremy Hylton

236654b

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

[diff] [blame]

409

410

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

411

headers to send with the request.

Georg Brandl

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

[diff] [blame]

412

Senthil Kumaran

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

[diff] [blame]

413

.. versionadded:: 3.2

Georg Brandl

09a7df8

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

[diff] [blame]

414

*body* can now be an iterable.

Senthil Kumaran

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

[diff] [blame]

415

Georg Brandl

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

[diff] [blame]

416

.. method:: HTTPConnection.getresponse()

417

418

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

419

Returns an :class:`HTTPResponse` instance.

.. note::

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

424

request to the server.

425

426

427

.. method:: HTTPConnection.set_debuglevel(level)

428

R. David Murray

d89bc3f

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

[diff] [blame]

429

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

430

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

431

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

432

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

Georg Brandl

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

[diff] [blame]

433

Mark Dickinson

574b1d6

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

[diff] [blame]

434

.. versionadded:: 3.1

Benjamin Peterson

fa0d703

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

[diff] [blame]

435

Georg Brandl

67b21b7

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

[diff] [blame]

436

Senthil Kumaran

7e5229c

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

[diff] [blame]

437

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

Senthil Kumaran

97f0c6b

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

[diff] [blame]

438

439

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

440

is required to a HTTPS Connection through a proxy server.

441

Sandro Tosi

44f568c

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

[diff] [blame]

442

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]

443

with the CONNECT request.

444

Senthil Kumaran

2e910fd

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

[diff] [blame]

445

.. versionadded:: 3.2

Georg Brandl

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

[diff] [blame]

446

Georg Brandl

67b21b7

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

[diff] [blame]

447

Georg Brandl

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

[diff] [blame]

448

.. method:: HTTPConnection.connect()

449

450

Connect to the server specified when the object was created.

451

452

453

.. method:: HTTPConnection.close()

454

455

Close the connection to the server.

456

457

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

458

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

459

460

Georg Brandl

036490d

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

[diff] [blame]

461

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

Georg Brandl

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

[diff] [blame]

462

463

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

464

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

465

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

466

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

467

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

468

values.

469

Georg Brandl

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

[diff] [blame]

470

471

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

472

473

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

474

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

475

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]

479

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

Georg Brandl

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

[diff] [blame]

480

Senthil Kumaran

5d0de3f

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

[diff] [blame]

481

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]

482

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

483

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

484

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

485

separate packet.

Georg Brandl

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

[diff] [blame]

486

487

.. method:: HTTPConnection.send(data)

488

489

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

490

: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]

499

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

500

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

501

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

502

statement.

Georg Brandl

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

[diff] [blame]

503

504

505

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

506

507

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

508

509

Georg Brandl

036490d

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

[diff] [blame]

510

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

Georg Brandl

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

[diff] [blame]

511

Senthil Kumaran

790f831

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

[diff] [blame]

512

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

513

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

514

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

515

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

Georg Brandl

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

[diff] [blame]

516

517

518

.. method:: HTTPResponse.getheaders()

519

520

Return a list of (header, value) tuples.

521

Senthil Kumaran

ceff566

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

[diff] [blame]

522

.. method:: HTTPResponse.fileno()

523

524

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

Georg Brandl

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

[diff] [blame]

525

526

.. attribute:: HTTPResponse.msg

527

Jeremy Hylton

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

[diff] [blame]

528

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

529

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

530

:class:`email.message.Message`.

Georg Brandl

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

[diff] [blame]

531

532

533

.. attribute:: HTTPResponse.version

534

535

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

536

537

538

.. attribute:: HTTPResponse.status

539

540

Status code returned by server.

541

542

543

.. attribute:: HTTPResponse.reason

544

545

Reason phrase returned by server.

546

547

Jeremy Hylton

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

[diff] [blame]

548

.. attribute:: HTTPResponse.debuglevel

549

Georg Brandl

ef871f6

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

[diff] [blame]

550

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

Jeremy Hylton

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

[diff] [blame]

551

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

552

Senthil Kumaran

ce9b596

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

[diff] [blame]

553

.. attribute:: HTTPResponse.closed

554

Senthil Kumaran

fd8d7e9

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

[diff] [blame]

555

Is True if the stream is closed.

Jeremy Hylton

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

[diff] [blame]

556

Georg Brandl

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

[diff] [blame]

Examples

--------

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

561

Georg Brandl

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

[diff] [blame]

562

>>> import http.client

563

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

Georg Brandl

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

[diff] [blame]

564

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

565

>>> r1 = conn.getresponse()

Georg Brandl

6911e3c

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

[diff] [blame]

566

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

Georg Brandl

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

[diff] [blame]

567

200 OK

Senthil Kumaran

ce9b596

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

[diff] [blame]

568

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

569

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

570

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

571

>>> r1 = conn.getresponse()

572

>>> while not r1.closed:

573

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

574

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

575

...

576

>>> # Example of an invalid request

Georg Brandl

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

[diff] [blame]

577

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

578

>>> r2 = conn.getresponse()

Georg Brandl

6911e3c

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

[diff] [blame]

579

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

Georg Brandl

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

[diff] [blame]

580

404 Not Found

581

>>> data2 = r2.read()

582

>>> conn.close()

583

Fred Drake

1587e3d

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

[diff] [blame]

584

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

585

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

Senthil Kumaran

71fb6c8

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

[diff] [blame]

586

587

>>> import http.client

588

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

589

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

590

>>> res = conn.getresponse()

591

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

592

200 OK

593

>>> data = res.read()

>>> print(len(data))

0

>>> data == b''

True

Georg Brandl

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

[diff] [blame]

599

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

600

Senthil Kumaran

aca8fd7

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

[diff] [blame]

601

>>> import http.client, urllib.parse

Senthil Kumaran

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

[diff] [blame]

602

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

Georg Brandl

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

[diff] [blame]

603

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

604

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

Senthil Kumaran

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

[diff] [blame]

605

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

606

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

Georg Brandl

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

[diff] [blame]

607

>>> response = conn.getresponse()

Georg Brandl

6911e3c

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

[diff] [blame]

608

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

Senthil Kumaran

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

[diff] [blame]

609

302 Found

Georg Brandl

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

[diff] [blame]

610

>>> data = response.read()

Senthil Kumaran

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

[diff] [blame]

611

>>> data

612

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]

613

>>> conn.close()

614

Jeremy Hylton

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

[diff] [blame]

615

616

.. _httpmessage-objects:

HTTPMessage Objects

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

Benjamin Peterson

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

[diff] [blame]

621

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

622

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

Jeremy Hylton