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>

52

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

53

</dt><dd>

54

<dl>

55

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

56

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

Joe Gregorio

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

[diff] [blame^]

57

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

Joe Gregorio

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

[diff] [blame]

58

</dt></dl>

59

</dd>

60

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

Joe Gregorio

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

[diff] [blame]

61

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

69

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

70

71

72

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

73

74

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

75

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

76

77

Args:

78

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

79

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

80

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

81

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

82

83

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

84

85

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

86

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

87

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

88

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

89

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

90

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

91

request id, to avoid such an error.

92

93

Args:

94

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

95

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

96

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

97

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

98

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

99

the callback with the response.

Returns:

None

Raises:

BatchError if a resumable request is added to a batch.

106

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

107

108

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

109

110

Args:

111

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

112

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

113

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.

120

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

121

122

<hr>

123

Data descriptors defined here:

124

125

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

126

</dl>

127

<dl><dt>__weakref__</dt>

128

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

135

136

137

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

138

139

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

140

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

141

filename: string, absolute filename to read response from

142

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

143

144

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

145

146

<hr>

147

Data descriptors defined here:

148

149

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

150

</dl>

151

<dl><dt>__weakref__</dt>

152

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

159

160

161

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

162

163

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

164

call. Create an instance initialized with the desired response headers

165

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

166

167

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

168

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

169

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

170

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

171

])

172

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

173

174

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

175

behavours that are helpful in testing.

176

177

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

178

'echo_request_headers_as_json' means return the request headers in

179

the response body

180

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

181

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

182

183

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

184

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

185

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

186

187

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

188

189

<hr>

190

Data descriptors defined here:

191

192

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

193

</dl>

194

<dl><dt>__weakref__</dt>

195

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

201

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

202

203

204

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

205

206

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

Joe Gregorio

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

[diff] [blame]

207

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

208

209

Args:

210

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]

211

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

212

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

213

on an error.

Joe Gregorio

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

[diff] [blame]

214

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

215

method: string, the HTTP method to use

Joe Gregorio

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

[diff] [blame]

216

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

Joe Gregorio

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

[diff] [blame]

217

headers: dict, the HTTP request headers

Joe Gregorio

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

[diff] [blame]

218

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

Joe Gregorio

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

[diff] [blame]

219

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]

220

221

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

222

223

Args:

224

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

225

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

226

227

Returns:

228

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.

233

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

234

Joe Gregorio

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

[diff] [blame]

235

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

236

237

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

Joe Gregorio

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

[diff] [blame]

238

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-04-13 07:58:30 -0400

[diff] [blame]

242

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

Joe Gregorio

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

[diff] [blame]

243

chunksize=1000, resumable=True)

244

request = service.objects().insert(

245

bucket=buckets['items'][0]['id'],

name='smiley.png',

media_body=media)

response = None

while response is None:

251

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

252

if status:

253

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

258

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

259

260

Raises:

261

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

262

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

Joe Gregorio

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

[diff] [blame]

263

264

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

265

266

<hr>

267

Static methods defined here:

268

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

269

Joe Gregorio

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

[diff] [blame]

270

<hr>

271

Data descriptors defined here:

272

273

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

274

</dl>

275

<dl><dt>__weakref__</dt>

276

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

282

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

283

284

285

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

286

287

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

288

289

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

290

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

291

292

Args:

293

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

294

content: string, the response body

295

postproc: callable, the post processing function usually supplied by

296

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

297

298

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

299

300

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

301

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

302

303

<hr>

304

Data descriptors defined here:

305

306

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

307

</dl>

308

<dl><dt>__weakref__</dt>

309

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

</dl>

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

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

316

317

318

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

319

320

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

321

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

322

323

Joe Gregorio

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

[diff] [blame^]

324

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

325

chunksize=1024*1024, resumable=True)

Joe Gregorio

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

[diff] [blame]

326

service.objects().insert(

327

bucket=buckets['items'][0]['id'],

328

name='smiley.png',

329

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

330

331

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

332

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

333

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

334

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

335

</dl>

336

<hr>

337

Methods defined here:

Joe Gregorio

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

[diff] [blame^]

338

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

339

340

Args:

341

filename: string, Name of the file.

342

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

343

guessed from the file extension.

344

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

345

used if resumable=True.

346

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

347

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

348

Joe Gregorio

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

[diff] [blame^]

349

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

350

351

Returns:

352

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

Joe Gregorio

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

[diff] [blame]

353

354

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

355

356

Args:

357

begin: int, offset from beginning of file.

358

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

359

360

Returns:

361

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

362

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

363

Joe Gregorio

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

[diff] [blame^]

364

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

365

366

Returns:

367

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

Joe Gregorio

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

[diff] [blame]

368

Joe Gregorio

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

[diff] [blame^]

369

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

370

371

Returns:

372

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

Joe Gregorio

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

[diff] [blame]

373

Joe Gregorio

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

[diff] [blame^]

374

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

375

376

Returns:

377

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]

378

379

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

380

381

Returns:

382

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

391

<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

392

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

393

394

Args:

395

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

396

397

Returns:

398

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

403

404

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

405

</dl>

406

<dl><dt>__weakref__</dt>

407

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

414

415

416

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

417

418

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

419

method. For example, if we had a service that allowed plain text:  </tt></td></tr>

420

421

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

422

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

423

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

424

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

425

</dl>

426

<hr>

427

Methods defined here:

Joe Gregorio

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

[diff] [blame^]

428

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

429

430

Args:

431

body: string, Bytes of body content.

432

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

433

'application/octet-stream'.

434

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

435

used if resumable=True.

436

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

437

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

438

439

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

440

441

Returns:

442

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

443

444

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

445

446

Args:

447

begin: int, offset from beginning of file.

448

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

449

450

Returns:

451

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

452

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

453

454

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

455

456

Returns:

457

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

458

459

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

460

461

Returns:

462

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

463

464

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

465

466

Returns:

Joe Gregorio

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

[diff] [blame^]

467

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]

468

469

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

470

471

Returns:

472

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

481

<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

482

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

483

484

Args:

485

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

486

487

Returns:

488

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

493

494

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

495

</dl>

496

<dl><dt>__weakref__</dt>

497

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

503

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

504

505

506

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

507

508

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

509

with this class also.

510

511

512

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

513

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

514

chunksize=1024*1024, resumable=True)

515

service.objects().insert(

516

bucket='a_bucket_id',

517

name='smiley.png',

518

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

519

520

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

521

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

522

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

523

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

524

</dl>

525

<hr>

526

Methods defined here:

527

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

528

529

Args:

530

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

531

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

532

guessed from the file extension.

533

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

534

used if resumable=True.

535

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

536

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

537

538

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

539

540

Returns:

541

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

542

543

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

544

545

Args:

546

begin: int, offset from beginning of file.

547

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

548

549

Returns:

550

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

551

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

552

553

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

554

555

Returns:

556

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

557

558

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

559

560

Returns:

561

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

562

563

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

564

565

Returns:

566

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

567

568

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

569

570

<hr>

571

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

572

<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

573

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

574

575

Args:

576

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

577

578

Returns:

579

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

584

585

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

586

</dl>

587

<dl><dt>__weakref__</dt>

588

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

594

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

595

596

597

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

598

Joe Gregorio

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

[diff] [blame^]

599

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

600

601

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

602

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

603

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

604

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

605

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

606

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]

607

608

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

Joe Gregorio

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

[diff] [blame^]

609

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

610

611

Returns:

612

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

Joe Gregorio

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

[diff] [blame]

613

Joe Gregorio

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

[diff] [blame^]

614

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

615

616

Args:

617

begin: int, offset from beginning of file.

618

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

619

620

Returns:

621

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

622

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

Joe Gregorio

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

[diff] [blame]

623

Joe Gregorio

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

[diff] [blame^]

624

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

625

626

Returns:

627

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

Joe Gregorio

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

[diff] [blame]

628

Joe Gregorio

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

[diff] [blame^]

629

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

630

631

Returns:

632

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

Joe Gregorio

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

[diff] [blame]

633

Joe Gregorio

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

[diff] [blame^]

634

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

635

636

Returns:

637

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]

638

639

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

640

641

Returns:

642

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

643

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

644

645

<hr>

646

Class methods defined here:

647

<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

648

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

649

650

Args:

651

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

652

653

Returns:

654

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

<hr>

Data descriptors defined here:

659

660

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

661

</dl>

662

<dl><dt>__weakref__</dt>

663

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

670

671

672

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

673

674

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

675

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

676

677

Args:

678

resumable_progress: int, bytes sent so far.

Joe Gregorio

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

[diff] [blame^]

679

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

680

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

Joe Gregorio

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

[diff] [blame]

681

Joe Gregorio

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

[diff] [blame^]

682

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

683

684

Returns:

685

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

686

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

Joe Gregorio

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

[diff] [blame]

687

688

<hr>

689

Data descriptors defined here:

690

691

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

692

</dl>

693

<dl><dt>__weakref__</dt>

694

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

700

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

701

702

703

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

704

705

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

Joe Gregorio

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

[diff] [blame]

706

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

707

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

708

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

709

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

710

the body and UnexpectedBodyError will be raised on inequality.

Joe Gregorio

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

[diff] [blame]

711

712

Example:

713

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

714

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

715

{

Joe Gregorio

c4fc095

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

[diff] [blame]

716

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

Joe Gregorio

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

[diff] [blame]

717

}

718

)

Joe Gregorio

c4fc095

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

[diff] [blame]

719

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

Joe Gregorio

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

[diff] [blame]

720

721

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

Joe Gregorio

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

[diff] [blame]

722

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

723

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]

724

in the discovery document.

Joe Gregorio

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

[diff] [blame]

725

726

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

727

728

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

Joe Gregorio

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

[diff] [blame]

729

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

730

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

731

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

732

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

733

Joe Gregorio

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

[diff] [blame]

734

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

735

736

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

737

that can replace the class HttpResponse.

738

739

responses - A dictionary that maps methodIds into tuples

740

of (httplib2.Response, content). The methodId

741

comes from the 'rpcName' field in the discovery

Joe Gregorio

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

[diff] [blame]

742

document.

743

check_unexpected - A boolean setting whether or not UnexpectedMethodError

744

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

Joe Gregorio

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

[diff] [blame]

745

746

<hr>

747

Data descriptors defined here:

748

749

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

750

</dl>

751

<dl><dt>__weakref__</dt>

752

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

753

</dl>

754

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

755

Joe Gregorio

20a5aa9

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

[diff] [blame]

756

757

758

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

759

760

Joe Gregorio

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

[diff] [blame]

761

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

762

763

Args:

764

http - An instance of httplib2.Http

765

or something that acts like it.

766

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

767

768

Returns:

769

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")

775

776

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

777

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

778

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

779

Args:

780

http - An instance of httplib2.Http

781

or something that acts like it.

782

783

Returns:

784

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")

790

791

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

792

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

793

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

794

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

795

Joe Gregorio

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

[diff] [blame]

Joe Gregorio

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

[diff] [blame^]

801

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

802

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

Joe Gregorio