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

14

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]

15

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

Georg Brandl

0f7ede4

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

[diff] [blame]

16

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

HTTPS support is only available if the :mod:`socket` module was compiled with

21

SSL support.

22

Georg Brandl

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

[diff] [blame]

23

The module provides the following classes:

24

25

Gregory P. Smith

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

[diff] [blame]

26

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

Georg Brandl

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

[diff] [blame]

27

28

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

Alexandre Vassalotti

5f8ced2

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

[diff] [blame]

29

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

30

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

31

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

Benjamin Peterson

f608c61

2008-11-16 18:33:53 +0000

[diff] [blame]

32

used. When True, the optional parameter *strict* (which defaults to a false

33

value) causes ``BadStatusLine`` to

Alexandre Vassalotti

5f8ced2

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

[diff] [blame]

34

be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1

35

status line. If the optional *timeout* parameter is given, blocking

36

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

Georg Brandl

f78e02b

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

[diff] [blame]

37

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

Gregory P. Smith

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

[diff] [blame]

38

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

39

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

Georg Brandl

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

[diff] [blame]

40

41

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

42

at the same host and port::

43

Georg Brandl

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

[diff] [blame]

44

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

45

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

46

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

47

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

Georg Brandl

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

[diff] [blame]

48

Gregory P. Smith

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

[diff] [blame]

49

.. versionchanged:: 3.2

50

*source_address* was added.

Georg Brandl

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

[diff] [blame]

51

Gregory P. Smith

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

[diff] [blame]

52

53

.. class:: HTTPSConnection(host, port=None, key_file=None, cert_file=None, strict=None[, timeout[, source_address]])

Georg Brandl

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

[diff] [blame]

54

55

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

56

secure servers. Default port is ``443``. *key_file* is the name of a PEM

57

formatted file that contains your private key. *cert_file* is a PEM formatted

58

certificate chain file.

59

Georg Brandl

e720c0a

2009-04-27 16:20:50 +0000

[diff] [blame]

60

.. note::

Georg Brandl

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

[diff] [blame]

61

Georg Brandl

e720c0a

2009-04-27 16:20:50 +0000

[diff] [blame]

62

This does not do any certificate verification.

Georg Brandl

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

[diff] [blame]

63

Gregory P. Smith

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

[diff] [blame]

64

.. versionchanged:: 3.2

65

*source_address* was added.

66

Georg Brandl

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

[diff] [blame]

67

Georg Brandl

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

[diff] [blame]

68

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

Georg Brandl

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

[diff] [blame]

69

Jeremy Hylton

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

[diff] [blame]

70

Class whose instances are returned upon successful connection. Not

71

instantiated directly by user.

Georg Brandl

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

[diff] [blame]

72

Georg Brandl

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

[diff] [blame]

73

74

The following exceptions are raised as appropriate:

75

76

77

.. exception:: HTTPException

78

79

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

80

:exc:`Exception`.

81

Georg Brandl

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

[diff] [blame]

82

83

.. exception:: NotConnected

84

85

A subclass of :exc:`HTTPException`.

86

Georg Brandl

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

[diff] [blame]

87

88

.. exception:: InvalidURL

89

90

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

91

non-numeric or empty.

92

Georg Brandl

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

[diff] [blame]

93

94

.. exception:: UnknownProtocol

95

96

A subclass of :exc:`HTTPException`.

97

Georg Brandl

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

[diff] [blame]

98

99

.. exception:: UnknownTransferEncoding

100

101

A subclass of :exc:`HTTPException`.

102

Georg Brandl

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

[diff] [blame]

103

104

.. exception:: UnimplementedFileMode

105

106

A subclass of :exc:`HTTPException`.

107

Georg Brandl

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

[diff] [blame]

108

109

.. exception:: IncompleteRead

110

111

A subclass of :exc:`HTTPException`.

112

Georg Brandl

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

[diff] [blame]

113

114

.. exception:: ImproperConnectionState

115

116

A subclass of :exc:`HTTPException`.

117

Georg Brandl

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

[diff] [blame]

118

119

.. exception:: CannotSendRequest

120

121

A subclass of :exc:`ImproperConnectionState`.

122

Georg Brandl

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

[diff] [blame]

123

124

.. exception:: CannotSendHeader

125

126

A subclass of :exc:`ImproperConnectionState`.

127

Georg Brandl

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

[diff] [blame]

128

129

.. exception:: ResponseNotReady

130

131

A subclass of :exc:`ImproperConnectionState`.

132

Georg Brandl

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

[diff] [blame]

133

134

.. exception:: BadStatusLine

135

136

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

137

status code that we don't understand.

138

Georg Brandl

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

[diff] [blame]

139

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``).

150

151

and also the following constants for integer status codes:

152

153

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

154

| Constant | Value | Definition |

155

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

156

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

157

| | | 10.1.1 |

158

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

159

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

160

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

161

| | | 10.1.2 |

162

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

163

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

164

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

165

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

166

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

167

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

168

| | | 10.2.1 |

169

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

170

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

171

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

172

| | | 10.2.2 |

173

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

174

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

175

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

176

| | | 10.2.3 |

177

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

178

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

179

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

180

| | | 10.2.4 |

181

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

182

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

183

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

184

| | | 10.2.5 |

185

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

186

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

187

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

188

| | | 10.2.6 |

189

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

190

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

191

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

192

| | | 10.2.7 |

193

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

194

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

195

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

196

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

197

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

198

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

199

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

200

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

201

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

202

| | | 10.3.1 |

203

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

204

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

205

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

206

| | | 10.3.2 |

207

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

208

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

209

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

210

| | | 10.3.3 |

211

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

212

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

213

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

214

| | | 10.3.4 |

215

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

216

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

217

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

218

| | | 10.3.5 |

219

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

220

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

221

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

222

| | | 10.3.6 |

223

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

224

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

225

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

226

| | | 10.3.8 |

227

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

228

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

229

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

230

| | | 10.4.1 |

231

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

232

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

233

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

234

| | | 10.4.2 |

235

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

236

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

237

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

238

| | | 10.4.3 |

239

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

240

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

241

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

242

| | | 10.4.4 |

243

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

244

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

245

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

246

| | | 10.4.5 |

247

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

248

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

249

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

250

| | | 10.4.6 |

251

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

252

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

253

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

254

| | | 10.4.7 |

255

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

256

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

257

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

258

| | | 10.4.8 |

259

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

260

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

261

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

262

| | | 10.4.9 |

263

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

264

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

265

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

266

| | | 10.4.10 |

267

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

268

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

269

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

270

| | | 10.4.11 |

271

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

272

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

273

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

274

| | | 10.4.12 |

275

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

276

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

277

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

278

| | | 10.4.13 |

279

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

280

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

281

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

282

| | | 10.4.14 |

283

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

284

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

285

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

286

| | | 10.4.15 |

287

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

288

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

289

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

290

| | | 10.4.16 |

291

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

292

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

293

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

294

| | | 10.4.17 |

295

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

296

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

297

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

298

| | | 10.4.18 |

299

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

300

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

301

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

302

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

303

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

304

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

305

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

306

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

307

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

308

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

309

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

310

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

311

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

312

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

313

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

314

| | | 10.5.1 |

315

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

316

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

317

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

318

| | | 10.5.2 |

319

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

320

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

321

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

322

| | | 10.5.3 |

323

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

324

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

325

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

326

| | | 10.5.4 |

327

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

328

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

329

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

330

| | | 10.5.5 |

331

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

332

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

333

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

334

| | | 10.5.6 |

335

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

336

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

337

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

338

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

339

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

340

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

341

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

342

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

.. data:: responses

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

348

Georg Brandl

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

[diff] [blame]

349

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

Georg Brandl

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

[diff] [blame]

350

Georg Brandl

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

[diff] [blame]

351

352

.. _httpconnection-objects:

353

354

HTTPConnection Objects

355

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

356

357

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

358

359

Georg Brandl

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

[diff] [blame]

360

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

Georg Brandl

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

[diff] [blame]

361

Jeremy Hylton

236654b

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

[diff] [blame]

362

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

363

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

364

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

365

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

366

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

367

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

368

string.

Georg Brandl

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

[diff] [blame]

369

Jeremy Hylton

236654b

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

[diff] [blame]

370

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

371

contents of the file is sent; this file object should support

372

``fileno()`` and ``read()`` methods. The header Content-Length is

373

automatically set to the length of the file as reported by

374

stat.

375

376

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

377

headers to send with the request.

Georg Brandl

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

[diff] [blame]

378

379

.. method:: HTTPConnection.getresponse()

380

381

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

382

Returns an :class:`HTTPResponse` instance.

.. note::

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

387

request to the server.

388

389

390

.. method:: HTTPConnection.set_debuglevel(level)

391

392

Set the debugging level (the amount of debugging output printed). The default

393

debug level is ``0``, meaning no debugging output is printed.

394

Mark Dickinson

574b1d6

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

[diff] [blame]

395

.. versionadded:: 3.1

Benjamin Peterson

fa0d703

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

[diff] [blame]

396

Senthil Kumaran

7e5229c

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

[diff] [blame]

397

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

Senthil Kumaran

97f0c6b

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

[diff] [blame]

398

399

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

400

is required to a HTTPS Connection through a proxy server.

401

Senthil Kumaran

7e5229c

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

[diff] [blame]

402

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

403

with the CONNECT request.

404

Senthil Kumaran

2e910fd

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

[diff] [blame]

405

.. versionadded:: 3.2

Georg Brandl

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

[diff] [blame]

406

407

.. method:: HTTPConnection.connect()

408

409

Connect to the server specified when the object was created.

410

411

412

.. method:: HTTPConnection.close()

413

414

Close the connection to the server.

415

416

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

417

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

418

419

Georg Brandl

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

[diff] [blame]

420

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

Georg Brandl

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

[diff] [blame]

421

422

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

423

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

424

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

425

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

426

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

427

values.

428

Georg Brandl

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

[diff] [blame]

429

430

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

431

432

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

433

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

434

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

an argument.

.. method:: HTTPConnection.endheaders()

439

440

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

441

442

443

.. method:: HTTPConnection.send(data)

444

445

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

446

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

455

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

456

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

457

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

458

statement.

Georg Brandl

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

[diff] [blame]

459

460

461

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

462

463

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

464

465

Georg Brandl

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

[diff] [blame]

466

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

Georg Brandl

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

[diff] [blame]

467

468

Get the contents of the header *name*, or *default* if there is no matching

header.

.. method:: HTTPResponse.getheaders()

473

474

Return a list of (header, value) tuples.

475

Georg Brandl

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

[diff] [blame]

476

477

.. attribute:: HTTPResponse.msg

478

Jeremy Hylton

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

[diff] [blame]

479

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

480

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

481

:class:`email.message.Message`.

Georg Brandl

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

[diff] [blame]

482

483

484

.. attribute:: HTTPResponse.version

485

486

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

487

488

489

.. attribute:: HTTPResponse.status

490

491

Status code returned by server.

492

493

494

.. attribute:: HTTPResponse.reason

495

496

Reason phrase returned by server.

497

498

Jeremy Hylton

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

[diff] [blame]

499

.. attribute:: HTTPResponse.debuglevel

500

Georg Brandl

ef871f6

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

[diff] [blame]

501

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

Jeremy Hylton

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

[diff] [blame]

502

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

503

504

Georg Brandl

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

[diff] [blame]

Examples

--------

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

509

Georg Brandl

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

[diff] [blame]

510

>>> import http.client

511

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

Georg Brandl

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

[diff] [blame]

512

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

513

>>> r1 = conn.getresponse()

Georg Brandl

6911e3c

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

[diff] [blame]

514

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

Georg Brandl

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

[diff] [blame]

515

200 OK

516

>>> data1 = r1.read()

517

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

518

>>> r2 = conn.getresponse()

Georg Brandl

6911e3c

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

[diff] [blame]

519

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

Georg Brandl

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

[diff] [blame]

520

404 Not Found

521

>>> data2 = r2.read()

522

>>> conn.close()

523

Fred Drake

1587e3d

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

[diff] [blame]

524

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

525

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

Senthil Kumaran

71fb6c8

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

[diff] [blame]

526

527

>>> import http.client

528

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

529

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

530

>>> res = conn.getresponse()

531

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

532

200 OK

533

>>> data = res.read()

>>> print(len(data))

0

>>> data == b''

True

Georg Brandl

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

[diff] [blame]

539

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

540

Senthil Kumaran

aca8fd7

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

[diff] [blame]

541

>>> import http.client, urllib.parse

542

>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})

Georg Brandl

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

[diff] [blame]

543

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

544

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

Georg Brandl

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

[diff] [blame]

545

>>> conn = http.client.HTTPConnection("musi-cal.mojam.com:80")

Georg Brandl

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

[diff] [blame]

546

>>> conn.request("POST", "/cgi-bin/query", params, headers)

547

>>> response = conn.getresponse()

Georg Brandl

6911e3c

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

[diff] [blame]

548

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

Georg Brandl

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

[diff] [blame]

549

200 OK

550

>>> data = response.read()

551

>>> conn.close()

552

Jeremy Hylton

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

[diff] [blame]

553

554

.. _httpmessage-objects:

HTTPMessage Objects

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

Benjamin Peterson

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

[diff] [blame]

559

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

560

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

Jeremy Hylton