Blame - docs/apiclient.http.html - platform/external/python/google-api-python-client

2010-12-09 16:34:22 -0500

[diff] [blame]

12

<tt>Classes to encapsulate a single HTTP request.

13

14

The classes implement a command pattern, with every

15

<a href="__builtin__.html#object">object</a> supporting an execute() method that does the

16

actuall HTTP request.</tt>

17

18

Joe Gregorio

6e53703

2011-02-09 23:04:26 -0500

[diff] [blame]

19

20

21

<big>Modules</big></td></tr>

22

23

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

24

<td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="StringIO.html">StringIO</a>

Joe Gregorio

3d55ac5

2012-02-21 10:11:19 -0500

[diff] [blame]

25

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

26

Joe Gregorio

3d55ac5

2012-02-21 10:11:19 -0500

[diff] [blame]

27

</td><td width="25%" valign=top><a href="gzip.html">gzip</a>

28

<a href="httplib2.html">httplib2</a>

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

29

<a href="apiclient.mimeparse.html">apiclient.mimeparse</a>

Joe Gregorio

3d55ac5

2012-02-21 10:11:19 -0500

[diff] [blame]

30

</td><td width="25%" valign=top><a href="mimetypes.html">mimetypes</a>

31

32

33

</td><td width="25%" valign=top><a href="urllib.html">urllib</a>

34

<a href="urlparse.html">urlparse</a>

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

35

36

</td></tr></table></td></tr></table>

Joe Gregorio

6e53703

2011-02-09 23:04:26 -0500

[diff] [blame]

37

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

38

39

40

<big>Classes</big></td></tr>

<dt><a href="__builtin__.html#object">__builtin__.object</a>

45

</dt><dd>

46

<dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

47

<dt><a href="apiclient.http.html#BatchHttpRequest">BatchHttpRequest</a>

48

</dt><dt><a href="apiclient.http.html#HttpMock">HttpMock</a>

49

</dt><dt><a href="apiclient.http.html#HttpMockSequence">HttpMockSequence</a>

50

</dt><dt><a href="apiclient.http.html#HttpRequest">HttpRequest</a>

51

</dt><dt><a href="apiclient.http.html#HttpRequestMock">HttpRequestMock</a>

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

52

</dt><dt><a href="apiclient.http.html#MediaDownloadProgress">MediaDownloadProgress</a>

53

</dt><dt><a href="apiclient.http.html#MediaIoBaseDownload">MediaIoBaseDownload</a>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

54

</dt><dt><a href="apiclient.http.html#MediaUpload">MediaUpload</a>

55

</dt><dd>

56

<dl>

57

<dt><a href="apiclient.http.html#MediaFileUpload">MediaFileUpload</a>

58

</dt><dt><a href="apiclient.http.html#MediaInMemoryUpload">MediaInMemoryUpload</a>

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

59

</dt><dt><a href="apiclient.http.html#MediaIoBaseUpload">MediaIoBaseUpload</a>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

60

</dt></dl>

61

</dd>

62

<dt><a href="apiclient.http.html#MediaUploadProgress">MediaUploadProgress</a>

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

63

</dt><dt><a href="apiclient.http.html#RequestMockBuilder">RequestMockBuilder</a>

</dt></dl>

</dd>

</dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

71

<a name="BatchHttpRequest">class BatchHttpRequest</a>(<a href="__builtin__.html#object">__builtin__.object</a>)</td></tr>

72

73

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

74

<td colspan=2><tt>Batches multiple <a href="#HttpRequest">HttpRequest</a> objects into a single HTTP request.

75

76

Example:

77

from apiclient.http import <a href="#BatchHttpRequest">BatchHttpRequest</a>

78

79

def list_animals(request_id, response):

80

"""Do something with the animals list response."""

81

pass

82

83

def list_farmers(request_id, response):

84

"""Do something with the farmers list response."""

85

pass

86

87

service = build('farm', 'v2')

88

89

batch = <a href="#BatchHttpRequest">BatchHttpRequest</a>()

90

91

batch.<a href="#BatchHttpRequest-add">add</a>(service.animals().list(), list_animals)

92

batch.<a href="#BatchHttpRequest-add">add</a>(service.farmers().list(), list_farmers)

93

batch.<a href="#BatchHttpRequest-execute">execute</a>(http)  </tt></td></tr>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

94

95

<td width="100%">Methods defined here:

96

<dl><dt><a name="BatchHttpRequest-__init__">__init__</a>(self, callback=None, batch_uri=None)</dt><dd><tt>Constructor for a <a href="#BatchHttpRequest">BatchHttpRequest</a>.

97

98

Args:

99

callback: callable, A callback to be called for each response, of the

100

form callback(id, response). The first parameter is the request id, and

101

the second is the deserialized response <a href="__builtin__.html#object">object</a>.

102

batch_uri: string, URI to send batch requests to.</tt></dd></dl>

103

104

<dl><dt><a name="BatchHttpRequest-add">add</a>(self, request, callback=None, request_id=None)</dt><dd><tt>Add a new request.

105

106

Every callback added will be paired with a unique id, the request_id. That

107

unique id will be passed back to the callback when the response comes back

108

from the server. The default behavior is to have the library generate it's

109

own unique id. If the caller passes in a request_id then they must ensure

110

uniqueness for each request_id, and if they are not an exception is

111

raised. Callers should either supply all request_ids or nevery supply a

112

request id, to avoid such an error.

113

114

Args:

115

request: <a href="#HttpRequest">HttpRequest</a>, Request to add to the batch.

116

callback: callable, A callback to be called for this response, of the

117

form callback(id, response). The first parameter is the request id, and

118

the second is the deserialized response <a href="__builtin__.html#object">object</a>.

119

request_id: string, A unique id for the request. The id will be passed to

120

the callback with the response.

Returns:

None

Raises:

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

126

BatchError if a media request is added to a batch.

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

127

KeyError is the request_id is not unique.</tt></dd></dl>

128

129

<dl><dt><a name="BatchHttpRequest-execute">execute</a>(self, http=None)</dt><dd><tt>Execute all the requests as a single batched HTTP request.

130

131

Args:

132

http: httplib2.Http, an http <a href="__builtin__.html#object">object</a> to be used in place of the one the

133

<a href="#HttpRequest">HttpRequest</a> request <a href="__builtin__.html#object">object</a> was constructed with.  If one isn't supplied

134

then use a http <a href="__builtin__.html#object">object</a> from the requests in this batch.

Returns:

None

Raises:

httplib2.Error if a transport error has occured.

141

apiclient.errors.BatchError if the response is the wrong format.</tt></dd></dl>

142

143

<hr>

144

Data descriptors defined here:

145

146

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

147

</dl>

148

<dl><dt>__weakref__</dt>

149

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

<a name="HttpMock">class HttpMock</a>(<a href="__builtin__.html#object">__builtin__.object</a>)</td></tr>

156

157

158

<td colspan=2><tt>Mock of httplib2.Http  </tt></td></tr>

159

160

<td width="100%">Methods defined here:

161

<dl><dt><a name="HttpMock-__init__">__init__</a>(self, filename, headers=None)</dt><dd><tt>Args:

162

filename: string, absolute filename to read response from

163

headers: dict, header to return with response</tt></dd></dl>

164

165

<dl><dt><a name="HttpMock-request">request</a>(self, uri, method='GET', body=None, headers=None, redirections=1, connection_type=None)</dt></dl>

166

167

<hr>

168

Data descriptors defined here:

169

170

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

171

</dl>

172

<dl><dt>__weakref__</dt>

173

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

<a name="HttpMockSequence">class HttpMockSequence</a>(<a href="__builtin__.html#object">__builtin__.object</a>)</td></tr>

180

181

182

<td colspan=2><tt>Mock of httplib2.Http

183

184

Mocks a sequence of calls to request returning different responses for each

185

call. Create an instance initialized with the desired response headers

186

and content and then use as if an httplib2.Http instance.

187

188

http = <a href="#HttpMockSequence">HttpMockSequence</a>([

189

({'status': '401'}, ''),

190

({'status': '200'}, '{"access_token":"1/3w","expires_in":3600}'),

191

({'status': '200'}, 'echo_request_headers'),

192

])

193

resp, content = http.<a href="#HttpMockSequence-request">request</a>("<a href="http://examples.com">http://examples.com</a>")

194

195

There are special values you can pass in for content to trigger

196

behavours that are helpful in testing.

197

198

'echo_request_headers' means return the request headers in the response body

199

'echo_request_headers_as_json' means return the request headers in

200

the response body

201

'echo_request_body' means return the request body in the response body

202

'echo_request_uri' means return the request uri in the response body  </tt></td></tr>

203

204

<td width="100%">Methods defined here:

205

<dl><dt><a name="HttpMockSequence-__init__">__init__</a>(self, iterable)</dt><dd><tt>Args:

206

iterable: iterable, a sequence of pairs of (headers, body)</tt></dd></dl>

207

208

<dl><dt><a name="HttpMockSequence-request">request</a>(self, uri, method='GET', body=None, headers=None, redirections=1, connection_type=None)</dt></dl>

209

210

<hr>

211

Data descriptors defined here:

212

213

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

214

</dl>

215

<dl><dt>__weakref__</dt>

216

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

222

<a name="HttpRequest">class HttpRequest</a>(<a href="__builtin__.html#object">__builtin__.object</a>)</td></tr>

223

224

225

<td colspan=2><tt>Encapsulates a single HTTP request.  </tt></td></tr>

226

227

<td width="100%">Methods defined here:

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

228

<dl><dt><a name="HttpRequest-__init__">__init__</a>(self, http, postproc, uri, method='GET', body=None, headers=None, methodId=None, resumable=None)</dt><dd><tt>Constructor for an <a href="#HttpRequest">HttpRequest</a>.

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

229

230

Args:

231

http: httplib2.Http, the transport <a href="__builtin__.html#object">object</a> to use to make a request

Joe Gregorio

abda96f

2011-02-11 20:19:33 -0500

[diff] [blame]

232

postproc: callable, called on the HTTP response and content to transform

233

it into a data <a href="__builtin__.html#object">object</a> before returning, or raising an exception

234

on an error.

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

235

uri: string, the absolute URI to send the request to

236

method: string, the HTTP method to use

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

237

body: string, the request body of the HTTP request,

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

238

headers: dict, the HTTP request headers

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

239

methodId: string, a unique identifier for the API method being called.

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

240

resumable: <a href="#MediaUpload">MediaUpload</a>, None if this is not a resumbale request.</tt></dd></dl>

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

241

242

<dl><dt><a name="HttpRequest-execute">execute</a>(self, http=None)</dt><dd><tt>Execute the request.

243

244

Args:

245

http: httplib2.Http, an http <a href="__builtin__.html#object">object</a> to be used in place of the

246

one the <a href="#HttpRequest">HttpRequest</a> request <a href="__builtin__.html#object">object</a> was constructed with.

247

248

Returns:

249

A deserialized <a href="__builtin__.html#object">object</a> model of the response body as determined

by the postproc.

Raises:

apiclient.errors.HttpError if the response was not a 2xx.

254

httplib2.Error if a transport error has occured.</tt></dd></dl>

255

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

256

<dl><dt><a name="HttpRequest-next_chunk">next_chunk</a>(self, http=None)</dt><dd><tt>Execute the next step of a resumable upload.

257

258

Can only be used if the method being executed supports media uploads and

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

259

the <a href="#MediaUpload">MediaUpload</a> <a href="__builtin__.html#object">object</a> passed in was flagged as using resumable upload.

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

Example:

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

263

media = <a href="#MediaFileUpload">MediaFileUpload</a>('cow.png', mimetype='image/png',

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

264

chunksize=1000, resumable=True)

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

265

request = farm.animals().insert(

266

id='cow',

267

name='cow.png',

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

media_body=media)

response = None

while response is None:

272

status, response = request.<a href="#HttpRequest-next_chunk">next_chunk</a>()

273

if status:

274

print "Upload %d%% complete." % int(status.progress() * 100)

Returns:

(status, body): (ResumableMediaStatus, <a href="__builtin__.html#object">object</a>)

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

279

The body will be None until the resumable media is fully uploaded.

280

281

Raises:

282

apiclient.errors.HttpError if the response was not a 2xx.

283

httplib2.Error if a transport error has occured.</tt></dd></dl>

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

284

285

<dl><dt><a name="HttpRequest-to_json">to_json</a>(self)</dt><dd><tt>Returns a JSON representation of the <a href="#HttpRequest">HttpRequest</a>.</tt></dd></dl>

286

287

<hr>

288

Static methods defined here:

289

<dl><dt><a name="HttpRequest-from_json">from_json</a>(s, http, postproc)</dt><dd><tt>Returns an <a href="#HttpRequest">HttpRequest</a> populated with info from a JSON <a href="__builtin__.html#object">object</a>.</tt></dd></dl>

290

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

291

<hr>

292

Data descriptors defined here:

293

294

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

295

</dl>

296

<dl><dt>__weakref__</dt>

297

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

303

<a name="HttpRequestMock">class HttpRequestMock</a>(<a href="__builtin__.html#object">__builtin__.object</a>)</td></tr>

304

305

306

<td colspan=2><tt>Mock of <a href="#HttpRequest">HttpRequest</a>.

307

308

Do not construct directly, instead use <a href="#RequestMockBuilder">RequestMockBuilder</a>.  </tt></td></tr>

309

310

<td width="100%">Methods defined here:

311

<dl><dt><a name="HttpRequestMock-__init__">__init__</a>(self, resp, content, postproc)</dt><dd><tt>Constructor for <a href="#HttpRequestMock">HttpRequestMock</a>

312

313

Args:

314

resp: httplib2.Response, the response to emulate coming from the request

315

content: string, the response body

316

postproc: callable, the post processing function usually supplied by

317

the model class. See model.JsonModel.response() as an example.</tt></dd></dl>

318

319

<dl><dt><a name="HttpRequestMock-execute">execute</a>(self, http=None)</dt><dd><tt>Execute the request.

320

321

Same behavior as <a href="#HttpRequest">HttpRequest</a>.<a href="#HttpRequestMock-execute">execute</a>(), but the response is

322

mocked and not really from an HTTP request/response.</tt></dd></dl>

323

324

<hr>

325

Data descriptors defined here:

326

327

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

328

</dl>

329

<dl><dt>__weakref__</dt>

330

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

336

<a name="MediaDownloadProgress">class MediaDownloadProgress</a>(<a href="__builtin__.html#object">__builtin__.object</a>)</td></tr>

337

338

339

<td colspan=2><tt>Status of a resumable download.  </tt></td></tr>

340

341

<td width="100%">Methods defined here:

342

<dl><dt><a name="MediaDownloadProgress-__init__">__init__</a>(self, resumable_progress, total_size)</dt><dd><tt>Constructor.

343

344

Args:

345

resumable_progress: int, bytes received so far.

346

total_size: int, total bytes in complete download.</tt></dd></dl>

347

348

<dl><dt><a name="MediaDownloadProgress-progress">progress</a>(self)</dt><dd><tt>Percent of download completed, as a float.

349

350

Returns:

351

the percentage complete as a float, returning 0.0 if the total size of

352

the download is unknown.</tt></dd></dl>

353

354

<hr>

355

Data descriptors defined here:

356

357

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

358

</dl>

359

<dl><dt>__weakref__</dt>

360

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

366

<a name="MediaFileUpload">class MediaFileUpload</a>(<a href="apiclient.http.html#MediaUpload">MediaUpload</a>)</td></tr>

367

368

369

<td colspan=2><tt>A <a href="#MediaUpload">MediaUpload</a> for a file.

370

371

Construct a <a href="#MediaFileUpload">MediaFileUpload</a> and pass as the media_body parameter of the

372

method. For example, if we had a service that allowed uploading images:

373

374

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

375

media = <a href="#MediaFileUpload">MediaFileUpload</a>('cow.png', mimetype='image/png',

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

376

chunksize=1024*1024, resumable=True)

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

377

farm.animals()..insert(

378

id='cow',

379

name='cow.png',

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

380

media_body=media).execute()  </tt></td></tr>

381

382

<td width="100%"><dl><dt>Method resolution order:</dt>

383

<dd><a href="apiclient.http.html#MediaFileUpload">MediaFileUpload</a></dd>

384

<dd><a href="apiclient.http.html#MediaUpload">MediaUpload</a></dd>

385

<dd><a href="__builtin__.html#object">__builtin__.object</a></dd>

386

</dl>

387

<hr>

388

Methods defined here:

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

389

<dl><dt><a name="MediaFileUpload-__init__">__init__</a>(self, filename, mimetype=None, chunksize=524288, resumable=False)</dt><dd><tt>Constructor.

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

390

391

Args:

392

filename: string, Name of the file.

393

mimetype: string, Mime-type of the file. If None then a mime-type will be

394

guessed from the file extension.

395

chunksize: int, File will be uploaded in chunks of this many bytes. Only

396

used if resumable=True.

397

resumable: bool, True if this is a resumable upload. False means upload

398

in a single request.</tt></dd></dl>

399

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

400

<dl><dt><a name="MediaFileUpload-chunksize">chunksize</a>(self)</dt><dd><tt>Chunk size for resumable uploads.

401

402

Returns:

403

Chunk size in bytes.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

404

405

<dl><dt><a name="MediaFileUpload-getbytes">getbytes</a>(self, begin, length)</dt><dd><tt>Get bytes from the media.

406

407

Args:

408

begin: int, offset from beginning of file.

409

length: int, number of bytes to read, starting at begin.

410

411

Returns:

412

A string of bytes read. May be shorted than length if EOF was reached

413

first.</tt></dd></dl>

414

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

415

<dl><dt><a name="MediaFileUpload-mimetype">mimetype</a>(self)</dt><dd><tt>Mime type of the body.

416

417

Returns:

418

Mime type.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

419

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

420

<dl><dt><a name="MediaFileUpload-resumable">resumable</a>(self)</dt><dd><tt>Whether this upload is resumable.

421

422

Returns:

423

True if resumable upload or False.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

424

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

425

<dl><dt><a name="MediaFileUpload-size">size</a>(self)</dt><dd><tt>Size of upload.

426

427

Returns:

428

Size of the body, or None of the size is unknown.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

429

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

430

<dl><dt><a name="MediaFileUpload-to_json">to_json</a>(self)</dt><dd><tt>Creating a JSON representation of an instance of <a href="#MediaFileUpload">MediaFileUpload</a>.

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

431

432

Returns:

433

string, a JSON representation of this instance, suitable to pass to

<hr>

Static methods defined here:

<hr>

Class methods inherited from <a href="apiclient.http.html#MediaUpload">MediaUpload</a>:

442

<dl><dt><a name="MediaFileUpload-new_from_json">new_from_json</a>(cls, s) from <a href="__builtin__.html#type">__builtin__.type</a></dt><dd><tt>Utility class method to instantiate a <a href="#MediaUpload">MediaUpload</a> subclass from a JSON

443

representation produced by <a href="#MediaFileUpload-to_json">to_json</a>().

444

445

Args:

446

s: string, JSON from <a href="#MediaFileUpload-to_json">to_json</a>().

447

448

Returns:

449

An instance of the subclass of <a href="#MediaUpload">MediaUpload</a> that was serialized with

<hr>

Data descriptors inherited from <a href="apiclient.http.html#MediaUpload">MediaUpload</a>:

454

455

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

456

</dl>

457

<dl><dt>__weakref__</dt>

458

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

<a name="MediaInMemoryUpload">class MediaInMemoryUpload</a>(<a href="apiclient.http.html#MediaUpload">MediaUpload</a>)</td></tr>

465

466

467

<td colspan=2><tt><a href="#MediaUpload">MediaUpload</a> for a chunk of bytes.

468

469

Construct a <a href="#MediaFileUpload">MediaFileUpload</a> and pass as the media_body parameter of the

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

470

method.  </tt></td></tr>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

471

472

<td width="100%"><dl><dt>Method resolution order:</dt>

473

<dd><a href="apiclient.http.html#MediaInMemoryUpload">MediaInMemoryUpload</a></dd>

474

<dd><a href="apiclient.http.html#MediaUpload">MediaUpload</a></dd>

475

<dd><a href="__builtin__.html#object">__builtin__.object</a></dd>

476

</dl>

477

<hr>

478

Methods defined here:

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

479

<dl><dt><a name="MediaInMemoryUpload-__init__">__init__</a>(self, body, mimetype='application/octet-stream', chunksize=524288, resumable=False)</dt><dd><tt>Create a new MediaBytesUpload.

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

480

481

Args:

482

body: string, Bytes of body content.

483

mimetype: string, Mime-type of the file or default of

484

'application/octet-stream'.

485

chunksize: int, File will be uploaded in chunks of this many bytes. Only

486

used if resumable=True.

487

resumable: bool, True if this is a resumable upload. False means upload

488

in a single request.</tt></dd></dl>

489

490

<dl><dt><a name="MediaInMemoryUpload-chunksize">chunksize</a>(self)</dt><dd><tt>Chunk size for resumable uploads.

491

492

Returns:

493

Chunk size in bytes.</tt></dd></dl>

494

495

<dl><dt><a name="MediaInMemoryUpload-getbytes">getbytes</a>(self, begin, length)</dt><dd><tt>Get bytes from the media.

496

497

Args:

498

begin: int, offset from beginning of file.

499

length: int, number of bytes to read, starting at begin.

500

501

Returns:

502

A string of bytes read. May be shorter than length if EOF was reached

503

first.</tt></dd></dl>

504

505

<dl><dt><a name="MediaInMemoryUpload-mimetype">mimetype</a>(self)</dt><dd><tt>Mime type of the body.

506

507

Returns:

508

Mime type.</tt></dd></dl>

509

510

<dl><dt><a name="MediaInMemoryUpload-resumable">resumable</a>(self)</dt><dd><tt>Whether this upload is resumable.

511

512

Returns:

513

True if resumable upload or False.</tt></dd></dl>

514

515

<dl><dt><a name="MediaInMemoryUpload-size">size</a>(self)</dt><dd><tt>Size of upload.

516

517

Returns:

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

518

Size of the body, or None of the size is unknown.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

519

520

<dl><dt><a name="MediaInMemoryUpload-to_json">to_json</a>(self)</dt><dd><tt>Create a JSON representation of a <a href="#MediaInMemoryUpload">MediaInMemoryUpload</a>.

521

522

Returns:

523

string, a JSON representation of this instance, suitable to pass to

<hr>

Static methods defined here:

<hr>

Class methods inherited from <a href="apiclient.http.html#MediaUpload">MediaUpload</a>:

532

<dl><dt><a name="MediaInMemoryUpload-new_from_json">new_from_json</a>(cls, s) from <a href="__builtin__.html#type">__builtin__.type</a></dt><dd><tt>Utility class method to instantiate a <a href="#MediaUpload">MediaUpload</a> subclass from a JSON

533

representation produced by <a href="#MediaInMemoryUpload-to_json">to_json</a>().

534

535

Args:

536

s: string, JSON from <a href="#MediaInMemoryUpload-to_json">to_json</a>().

537

538

Returns:

539

An instance of the subclass of <a href="#MediaUpload">MediaUpload</a> that was serialized with

<hr>

Data descriptors inherited from <a href="apiclient.http.html#MediaUpload">MediaUpload</a>:

544

545

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

546

</dl>

547

<dl><dt>__weakref__</dt>

548

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

554

<a name="MediaIoBaseDownload">class MediaIoBaseDownload</a>(<a href="__builtin__.html#object">__builtin__.object</a>)</td></tr>

555

556

557

<td colspan=2><tt>"Download media resources.

558

559

Note that the Python file <a href="__builtin__.html#object">object</a> is compatible with io.Base and can be used

560

with this class also.

Example:

request = farms.animals().get_media(id='cow')

565

fh = io.FileIO('cow.png', mode='wb')

566

downloader = <a href="#MediaIoBaseDownload">MediaIoBaseDownload</a>(fh, request, chunksize=1024*1024)

done = False

while done is False:

status, done = downloader.<a href="#MediaIoBaseDownload-next_chunk">next_chunk</a>()

571

if status:

572

print "Download %d%%." % int(status.progress() * 100)

573

print "Download Complete!"  </tt></td></tr>

574

575

<td width="100%">Methods defined here:

576

<dl><dt><a name="MediaIoBaseDownload-__init__">__init__</a>(self, fh, request, chunksize=524288)</dt><dd><tt>Constructor.

577

578

Args:

579

fh: io.Base or file <a href="__builtin__.html#object">object</a>, The stream in which to write the downloaded

580

bytes.

581

request: apiclient.http.<a href="#HttpRequest">HttpRequest</a>, the media request to perform in

582

chunks.

583

chunksize: int, File will be downloaded in chunks of this many bytes.</tt></dd></dl>

584

585

<dl><dt><a name="MediaIoBaseDownload-next_chunk">next_chunk</a>(self)</dt><dd><tt>Get the next chunk of the download.

586

587

Returns:

588

(status, done): (MediaDownloadStatus, boolean)

589

The value of 'done' will be True when the media has been fully

downloaded.

Raises:

apiclient.errors.HttpError if the response was not a 2xx.

594

httplib2.Error if a transport error has occured.</tt></dd></dl>

595

596

<hr>

597

Data descriptors defined here:

598

599

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

600

</dl>

601

<dl><dt>__weakref__</dt>

602

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

608

<a name="MediaIoBaseUpload">class MediaIoBaseUpload</a>(<a href="apiclient.http.html#MediaUpload">MediaUpload</a>)</td></tr>

609

610

611

<td colspan=2><tt>A <a href="#MediaUpload">MediaUpload</a> for a io.Base objects.

612

613

Note that the Python file <a href="__builtin__.html#object">object</a> is compatible with io.Base and can be used

614

with this class also.

615

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

616

fh = io.BytesIO('...Some data to upload...')

617

media = <a href="#MediaIoBaseUpload">MediaIoBaseUpload</a>(fh, mimetype='image/png',

618

chunksize=1024*1024, resumable=True)

Joe Gregorio

2012-06-15 14:14:17 -0400

[diff] [blame^]

619

farm.animals().insert(

620

id='cow',

621

name='cow.png',

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

622

media_body=media).execute()  </tt></td></tr>

623

624

<td width="100%"><dl><dt>Method resolution order:</dt>

625

<dd><a href="apiclient.http.html#MediaIoBaseUpload">MediaIoBaseUpload</a></dd>

626

<dd><a href="apiclient.http.html#MediaUpload">MediaUpload</a></dd>

627

<dd><a href="__builtin__.html#object">__builtin__.object</a></dd>

628

</dl>

629

<hr>

630

Methods defined here:

631

<dl><dt><a name="MediaIoBaseUpload-__init__">__init__</a>(self, fh, mimetype, chunksize=524288, resumable=False)</dt><dd><tt>Constructor.

632

633

Args:

Joe Gregorio

746096f

2012-06-15 10:53:36 -0400

[diff] [blame]

634

fh: io.Base or file <a href="__builtin__.html#object">object</a>, The source of the bytes to upload. MUST be

635

opened in blocking mode, do not use streams opened in non-blocking mode.

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

636

mimetype: string, Mime-type of the file. If None then a mime-type will be

637

guessed from the file extension.

638

chunksize: int, File will be uploaded in chunks of this many bytes. Only

639

used if resumable=True.

640

resumable: bool, True if this is a resumable upload. False means upload

641

in a single request.</tt></dd></dl>

642

643

<dl><dt><a name="MediaIoBaseUpload-chunksize">chunksize</a>(self)</dt><dd><tt>Chunk size for resumable uploads.

644

645

Returns:

646

Chunk size in bytes.</tt></dd></dl>

647

648

<dl><dt><a name="MediaIoBaseUpload-getbytes">getbytes</a>(self, begin, length)</dt><dd><tt>Get bytes from the media.

649

650

Args:

651

begin: int, offset from beginning of file.

652

length: int, number of bytes to read, starting at begin.

653

654

Returns:

655

A string of bytes read. May be shorted than length if EOF was reached

656

first.</tt></dd></dl>

657

658

<dl><dt><a name="MediaIoBaseUpload-mimetype">mimetype</a>(self)</dt><dd><tt>Mime type of the body.

659

660

Returns:

661

Mime type.</tt></dd></dl>

662

663

<dl><dt><a name="MediaIoBaseUpload-resumable">resumable</a>(self)</dt><dd><tt>Whether this upload is resumable.

664

665

Returns:

666

True if resumable upload or False.</tt></dd></dl>

667

668

<dl><dt><a name="MediaIoBaseUpload-size">size</a>(self)</dt><dd><tt>Size of upload.

669

670

Returns:

671

Size of the body, or None of the size is unknown.</tt></dd></dl>

672

673

<dl><dt><a name="MediaIoBaseUpload-to_json">to_json</a>(self)</dt><dd><tt>This upload type is not serializable.</tt></dd></dl>

674

675

<hr>

676

Class methods inherited from <a href="apiclient.http.html#MediaUpload">MediaUpload</a>:

677

<dl><dt><a name="MediaIoBaseUpload-new_from_json">new_from_json</a>(cls, s) from <a href="__builtin__.html#type">__builtin__.type</a></dt><dd><tt>Utility class method to instantiate a <a href="#MediaUpload">MediaUpload</a> subclass from a JSON

678

representation produced by <a href="#MediaIoBaseUpload-to_json">to_json</a>().

679

680

Args:

681

s: string, JSON from <a href="#MediaIoBaseUpload-to_json">to_json</a>().

682

683

Returns:

684

An instance of the subclass of <a href="#MediaUpload">MediaUpload</a> that was serialized with

<hr>

Data descriptors inherited from <a href="apiclient.http.html#MediaUpload">MediaUpload</a>:

689

690

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

691

</dl>

692

<dl><dt>__weakref__</dt>

693

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

699

<a name="MediaUpload">class MediaUpload</a>(<a href="__builtin__.html#object">__builtin__.object</a>)</td></tr>

700

701

702

<td colspan=2><tt>Describes a media <a href="__builtin__.html#object">object</a> to upload.

703

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

704

Base class that defines the interface of <a href="#MediaUpload">MediaUpload</a> subclasses.

705

706

Note that subclasses of <a href="#MediaUpload">MediaUpload</a> may allow you to control the chunksize

707

when upload a media <a href="__builtin__.html#object">object</a>. It is important to keep the size of the chunk as

708

large as possible to keep the upload efficient. Other factors may influence

709

the size of the chunk you use, particularly if you are working in an

710

environment where individual HTTP requests may have a hardcoded time limit,

711

such as under certain classes of requests under Google App Engine.  </tt></td></tr>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

712

713

<td width="100%">Methods defined here:

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

714

<dl><dt><a name="MediaUpload-chunksize">chunksize</a>(self)</dt><dd><tt>Chunk size for resumable uploads.

715

716

Returns:

717

Chunk size in bytes.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

718

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

719

<dl><dt><a name="MediaUpload-getbytes">getbytes</a>(self, begin, end)</dt><dd><tt>Get bytes from the media.

720

721

Args:

722

begin: int, offset from beginning of file.

723

length: int, number of bytes to read, starting at begin.

724

725

Returns:

726

A string of bytes read. May be shorter than length if EOF was reached

727

first.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

728

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

729

<dl><dt><a name="MediaUpload-mimetype">mimetype</a>(self)</dt><dd><tt>Mime type of the body.

730

731

Returns:

732

Mime type.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

733

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

734

<dl><dt><a name="MediaUpload-resumable">resumable</a>(self)</dt><dd><tt>Whether this upload is resumable.

735

736

Returns:

737

True if resumable upload or False.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

738

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

739

<dl><dt><a name="MediaUpload-size">size</a>(self)</dt><dd><tt>Size of upload.

740

741

Returns:

742

Size of the body, or None of the size is unknown.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

743

744

<dl><dt><a name="MediaUpload-to_json">to_json</a>(self)</dt><dd><tt>Create a JSON representation of an instance of <a href="#MediaUpload">MediaUpload</a>.

745

746

Returns:

747

string, a JSON representation of this instance, suitable to pass to

748

from_json().</tt></dd></dl>

749

750

<hr>

751

Class methods defined here:

752

<dl><dt><a name="MediaUpload-new_from_json">new_from_json</a>(cls, s) from <a href="__builtin__.html#type">__builtin__.type</a></dt><dd><tt>Utility class method to instantiate a <a href="#MediaUpload">MediaUpload</a> subclass from a JSON

753

representation produced by <a href="#MediaUpload-to_json">to_json</a>().

754

755

Args:

756

s: string, JSON from <a href="#MediaUpload-to_json">to_json</a>().

757

758

Returns:

759

An instance of the subclass of <a href="#MediaUpload">MediaUpload</a> that was serialized with

<hr>

Data descriptors defined here:

764

765

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

766

</dl>

767

<dl><dt>__weakref__</dt>

768

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

<a name="MediaUploadProgress">class MediaUploadProgress</a>(<a href="__builtin__.html#object">__builtin__.object</a>)</td></tr>

775

776

777

<td colspan=2><tt>Status of a resumable upload.  </tt></td></tr>

778

779

<td width="100%">Methods defined here:

780

<dl><dt><a name="MediaUploadProgress-__init__">__init__</a>(self, resumable_progress, total_size)</dt><dd><tt>Constructor.

781

782

Args:

783

resumable_progress: int, bytes sent so far.

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

784

total_size: int, total bytes in complete upload, or None if the total

785

upload size isn't known ahead of time.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

786

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

787

<dl><dt><a name="MediaUploadProgress-progress">progress</a>(self)</dt><dd><tt>Percent of upload completed, as a float.

788

789

Returns:

790

the percentage complete as a float, returning 0.0 if the total size of

791

the upload is unknown.</tt></dd></dl>

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

792

793

<hr>

794

Data descriptors defined here:

795

796

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

797

</dl>

798

<dl><dt>__weakref__</dt>

799

<dd><tt>list of weak references to the object (if defined)</tt></dd>

</dl>

</td></tr></table>

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

805

<a name="RequestMockBuilder">class RequestMockBuilder</a>(<a href="__builtin__.html#object">__builtin__.object</a>)</td></tr>

806

807

808

<td colspan=2><tt>A simple mock of <a href="#HttpRequest">HttpRequest</a>

809

810

Pass in a dictionary to the constructor that maps request methodIds to

Joe Gregorio

2011-09-15 09:53:21 -0400

[diff] [blame]

811

tuples of (httplib2.Response, content, opt_expected_body) that should be

812

returned when that method is called. None may also be passed in for the

813

httplib2.Response, in which case a 200 OK response will be generated.

814

If an opt_expected_body (str or dict) is provided, it will be compared to

815

the body and UnexpectedBodyError will be raised on inequality.

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

816

817

Example:

818

response = '{"data": {"id": "tag:google.c...'

819

requestBuilder = <a href="#RequestMockBuilder">RequestMockBuilder</a>(

820

{

Joe Gregorio

c4fc095

2011-11-09 12:21:11 -0500

[diff] [blame]

821

'plus.activities.get': (None, response),

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

822

}

823

)

Joe Gregorio

c4fc095

2011-11-09 12:21:11 -0500

[diff] [blame]

824

apiclient.discovery.build("plus", "v1", requestBuilder=requestBuilder)

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

825

826

Methods that you do not supply a response for will return a

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

827

200 OK with an empty string as the response content or raise an excpetion

828

if check_unexpected is set to True. The methodId is taken from the rpcName

Joe Gregorio

2011-09-15 09:53:21 -0400

[diff] [blame]

829

in the discovery document.

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

830

831

For more details see the project wiki.  </tt></td></tr>

832

833

<td width="100%">Methods defined here:

Joe Gregorio

2011-12-08 12:04:24 -0500

[diff] [blame]

834

<dl><dt><a name="RequestMockBuilder-__call__">__call__</a>(self, http, postproc, uri, method='GET', body=None, headers=None, methodId=None, resumable=None)</dt><dd><tt>Implements the callable interface that discovery.build() expects

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

835

of requestBuilder, which is to build an <a href="__builtin__.html#object">object</a> compatible with

836

<a href="#HttpRequest">HttpRequest</a>.execute(). See that method for the description of the

837

parameters and the expected response.</tt></dd></dl>

838

Joe Gregorio

2011-09-15 09:53:21 -0400

[diff] [blame]

839

<dl><dt><a name="RequestMockBuilder-__init__">__init__</a>(self, responses, check_unexpected=False)</dt><dd><tt>Constructor for <a href="#RequestMockBuilder">RequestMockBuilder</a>

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

840

841

The constructed <a href="__builtin__.html#object">object</a> should be a callable <a href="__builtin__.html#object">object</a>

842

that can replace the class HttpResponse.

843

844

responses - A dictionary that maps methodIds into tuples

845

of (httplib2.Response, content). The methodId

846

comes from the 'rpcName' field in the discovery

Joe Gregorio

2011-09-15 09:53:21 -0400

[diff] [blame]

847

document.

848

check_unexpected - A boolean setting whether or not UnexpectedMethodError

849

should be raised on unsupplied method.</tt></dd></dl>

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

850

851

<hr>

852

Data descriptors defined here:

853

854

<dd><tt>dictionary for instance variables (if defined)</tt></dd>

855

</dl>

856

<dl><dt>__weakref__</dt>

857

<dd><tt>list of weak references to the object (if defined)</tt></dd>

858

</dl>

859

</td></tr></table></td></tr></table>

860

Joe Gregorio

20a5aa9

2011-04-01 17:44:25 -0400

[diff] [blame]

861

862

863

<big>Functions</big></td></tr>

864

865

Joe Gregorio

2012-04-13 07:58:30 -0400

[diff] [blame]

866

<td width="100%"><dl><dt><a name="-set_user_agent">set_user_agent</a>(http, user_agent)</dt><dd><tt>Set the user-agent on every request.

867

868

Args:

869

http - An instance of httplib2.Http

870

or something that acts like it.

871

user_agent: string, the value for the user-agent header.

872

873

Returns:

874

A modified instance of http that was passed in.

Example:

h = httplib2.Http()

h = <a href="#-set_user_agent">set_user_agent</a>(h, "my-app-name/6.0")

880

881

Most of the time the user-agent will be set doing auth, this is for the rare

882

cases where you are accessing an unauthenticated endpoint.</tt></dd></dl>

883

<dl><dt><a name="-tunnel_patch">tunnel_patch</a>(http)</dt><dd><tt>Tunnel PATCH requests over POST.

Joe Gregorio

20a5aa9

2011-04-01 17:44:25 -0400

[diff] [blame]

884

Args:

885

http - An instance of httplib2.Http

886

or something that acts like it.

887

888

Returns:

889

A modified instance of http that was passed in.

Example:

h = httplib2.Http()

h = <a href="#-tunnel_patch">tunnel_patch</a>(h, "my-app-name/6.0")

895

896

Useful if you are running on a platform that doesn't support PATCH.

897

Apply this last if you are using OAuth 1.0, as changing the method

898

will result in a different signature.</tt></dd></dl>

899

</td></tr></table>

900

Joe Gregorio

2010-12-09 16:34:22 -0500

[diff] [blame]

Joe Gregorio

2012-06-14 09:10:14 -0400

[diff] [blame]

906

<td width="100%">DEFAULT_CHUNK_SIZE = 524288

907

__author__ = 'jcgregorio@google.com (Joe Gregorio)'</td></tr></table>

Joe Gregorio