blob: bd1a42b0241cc636c9693495a2356e1b9ed1659a [file] [log] [blame]
Bu Sun Kim02bae1c2019-06-14 13:33:59 -07001<?xml version="1.0" encoding="ascii"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "DTD/xhtml1-transitional.dtd">
4<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5<head>
6 <title>googleapiclient._helpers</title>
7 <link rel="stylesheet" href="epydoc.css" type="text/css" />
8 <script type="text/javascript" src="epydoc.js"></script>
9</head>
10
11<body bgcolor="white" text="black" link="blue" vlink="#204080"
12 alink="#204080">
13<!-- ==================== NAVIGATION BAR ==================== -->
14<table class="navbar" border="0" width="100%" cellpadding="0"
15 bgcolor="#a0c0ff" cellspacing="0">
16 <tr valign="middle">
17 <!-- Home link -->
18 <th>&nbsp;&nbsp;&nbsp;<a
19 href="googleapiclient-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
20
21 <!-- Tree link -->
22 <th>&nbsp;&nbsp;&nbsp;<a
23 href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
24
25 <!-- Index link -->
26 <th>&nbsp;&nbsp;&nbsp;<a
27 href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
28
29 <!-- Help link -->
30 <th>&nbsp;&nbsp;&nbsp;<a
31 href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
32
33 <th class="navbar" width="100%"></th>
34 </tr>
35</table>
36<table width="100%" cellpadding="0" cellspacing="0">
37 <tr valign="top">
38 <td width="100%">
39 <span class="breadcrumbs">
40 <a href="googleapiclient-module.html">Package&nbsp;googleapiclient</a> ::
41 Module&nbsp;_helpers
42 </span>
43 </td>
44 <td>
45 <table cellpadding="0" cellspacing="0">
46 <!-- hide/show private -->
47 <tr><td align="right"><span class="options">[<a href="javascript:void(0);" class="privatelink"
48 onclick="toggle_private();">hide&nbsp;private</a>]</span></td></tr>
49 <tr><td align="right"><span class="options"
50 >[<a href="frames.html" target="_top">frames</a
51 >]&nbsp;|&nbsp;<a href="googleapiclient._helpers-module.html"
52 target="_top">no&nbsp;frames</a>]</span></td></tr>
53 </table>
54 </td>
55 </tr>
56</table>
57<!-- ==================== MODULE DESCRIPTION ==================== -->
58<h1 class="epydoc">Module _helpers</h1><p class="nomargin-top"><span class="codelink"><a href="googleapiclient._helpers-pysrc.html">source&nbsp;code</a></span></p>
Dmitry Frenkel3e17f892020-10-06 16:46:05 -070059<p>Helper functions for commonly used utilities.</p>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -070060
61<!-- ==================== FUNCTIONS ==================== -->
62<a name="section-Functions"></a>
63<table class="summary" border="1" cellpadding="3"
64 cellspacing="0" width="100%" bgcolor="white">
65<tr bgcolor="#70b0f0" class="table-header">
66 <td colspan="2" class="table-header">
67 <table border="0" cellpadding="0" cellspacing="0" width="100%">
68 <tr valign="top">
69 <td align="left"><span class="table-header">Functions</span></td>
70 <td align="right" valign="top"
71 ><span class="options">[<a href="#section-Functions"
72 class="privatelink" onclick="toggle_private();"
73 >hide private</a>]</span></td>
74 </tr>
75 </table>
76 </td>
77</tr>
78<tr>
79 <td width="15%" align="right" valign="top" class="summary">
80 <span class="summary-type">&nbsp;</span>
81 </td><td class="summary">
82 <table width="100%" cellpadding="0" cellspacing="0" border="0">
83 <tr>
84 <td><span class="summary-sig"><a href="googleapiclient._helpers-module.html#positional" class="summary-sig-name">positional</a>(<span class="summary-sig-arg">max_positional_args</span>)</span><br />
Dmitry Frenkel3e17f892020-10-06 16:46:05 -070085 A decorator to declare that only the first N arguments may be positional.</td>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -070086 <td align="right" valign="top">
87 <span class="codelink"><a href="googleapiclient._helpers-pysrc.html#positional">source&nbsp;code</a></span>
88
89 </td>
90 </tr>
91 </table>
92
93 </td>
94 </tr>
95<tr>
96 <td width="15%" align="right" valign="top" class="summary">
97 <span class="summary-type">&nbsp;</span>
98 </td><td class="summary">
99 <table width="100%" cellpadding="0" cellspacing="0" border="0">
100 <tr>
101 <td><span class="summary-sig"><a href="googleapiclient._helpers-module.html#parse_unique_urlencoded" class="summary-sig-name">parse_unique_urlencoded</a>(<span class="summary-sig-arg">content</span>)</span><br />
102 Parses unique key-value parameters from urlencoded content.</td>
103 <td align="right" valign="top">
104 <span class="codelink"><a href="googleapiclient._helpers-pysrc.html#parse_unique_urlencoded">source&nbsp;code</a></span>
105
106 </td>
107 </tr>
108 </table>
109
110 </td>
111 </tr>
112<tr>
113 <td width="15%" align="right" valign="top" class="summary">
114 <span class="summary-type">&nbsp;</span>
115 </td><td class="summary">
116 <table width="100%" cellpadding="0" cellspacing="0" border="0">
117 <tr>
118 <td><span class="summary-sig"><a href="googleapiclient._helpers-module.html#update_query_params" class="summary-sig-name">update_query_params</a>(<span class="summary-sig-arg">uri</span>,
119 <span class="summary-sig-arg">params</span>)</span><br />
120 Updates a URI with new query parameters.</td>
121 <td align="right" valign="top">
122 <span class="codelink"><a href="googleapiclient._helpers-pysrc.html#update_query_params">source&nbsp;code</a></span>
123
124 </td>
125 </tr>
126 </table>
127
128 </td>
129 </tr>
130<tr class="private">
131 <td width="15%" align="right" valign="top" class="summary">
132 <span class="summary-type">&nbsp;</span>
133 </td><td class="summary">
134 <table width="100%" cellpadding="0" cellspacing="0" border="0">
135 <tr>
136 <td><span class="summary-sig"><a href="googleapiclient._helpers-module.html#_add_query_parameter" class="summary-sig-name" onclick="show_private();">_add_query_parameter</a>(<span class="summary-sig-arg">url</span>,
137 <span class="summary-sig-arg">name</span>,
138 <span class="summary-sig-arg">value</span>)</span><br />
139 Adds a query parameter to a url.</td>
140 <td align="right" valign="top">
141 <span class="codelink"><a href="googleapiclient._helpers-pysrc.html#_add_query_parameter">source&nbsp;code</a></span>
142
143 </td>
144 </tr>
145 </table>
146
147 </td>
148 </tr>
149</table>
150<!-- ==================== VARIABLES ==================== -->
151<a name="section-Variables"></a>
152<table class="summary" border="1" cellpadding="3"
153 cellspacing="0" width="100%" bgcolor="white">
154<tr bgcolor="#70b0f0" class="table-header">
155 <td colspan="2" class="table-header">
156 <table border="0" cellpadding="0" cellspacing="0" width="100%">
157 <tr valign="top">
158 <td align="left"><span class="table-header">Variables</span></td>
159 <td align="right" valign="top"
160 ><span class="options">[<a href="#section-Variables"
161 class="privatelink" onclick="toggle_private();"
162 >hide private</a>]</span></td>
163 </tr>
164 </table>
165 </td>
166</tr>
167<tr>
168 <td width="15%" align="right" valign="top" class="summary">
169 <span class="summary-type">&nbsp;</span>
170 </td><td class="summary">
171 <a name="logger"></a><span class="summary-name">logger</span> = <code title="logging.getLogger(__name__)">logging.getLogger(__name__)</code>
172 </td>
173 </tr>
174<tr>
175 <td width="15%" align="right" valign="top" class="summary">
176 <span class="summary-type">&nbsp;</span>
177 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700178 <a name="POSITIONAL_WARNING"></a><span class="summary-name">POSITIONAL_WARNING</span> = <code title="'WARNING'"><code class="variable-quote">'</code><code class="variable-string">WARNING</code><code class="variable-quote">'</code></code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700179 </td>
180 </tr>
181<tr>
182 <td width="15%" align="right" valign="top" class="summary">
183 <span class="summary-type">&nbsp;</span>
184 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700185 <a name="POSITIONAL_EXCEPTION"></a><span class="summary-name">POSITIONAL_EXCEPTION</span> = <code title="'EXCEPTION'"><code class="variable-quote">'</code><code class="variable-string">EXCEPTION</code><code class="variable-quote">'</code></code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700186 </td>
187 </tr>
188<tr>
189 <td width="15%" align="right" valign="top" class="summary">
190 <span class="summary-type">&nbsp;</span>
191 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700192 <a name="POSITIONAL_IGNORE"></a><span class="summary-name">POSITIONAL_IGNORE</span> = <code title="'IGNORE'"><code class="variable-quote">'</code><code class="variable-string">IGNORE</code><code class="variable-quote">'</code></code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700193 </td>
194 </tr>
195<tr>
196 <td width="15%" align="right" valign="top" class="summary">
197 <span class="summary-type">&nbsp;</span>
198 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700199 <a name="POSITIONAL_SET"></a><span class="summary-name">POSITIONAL_SET</span> = <code title="frozenset(['EXCEPTION', 'IGNORE', 'WARNING'])"><code class="variable-group">frozenset([</code><code class="variable-quote">'</code><code class="variable-string">EXCEPTION</code><code class="variable-quote">'</code><code class="variable-op">, </code><code class="variable-quote">'</code><code class="variable-string">IGNORE</code><code class="variable-quote">'</code><code class="variable-op">, </code><code class="variable-quote">'</code><code class="variable-string">WARNING</code><code class="variable-quote">'</code><code class="variable-group">])</code></code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700200 </td>
201 </tr>
202<tr>
203 <td width="15%" align="right" valign="top" class="summary">
204 <span class="summary-type">&nbsp;</span>
205 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700206 <a name="positional_parameters_enforcement"></a><span class="summary-name">positional_parameters_enforcement</span> = <code title="'WARNING'"><code class="variable-quote">'</code><code class="variable-string">WARNING</code><code class="variable-quote">'</code></code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700207 </td>
208 </tr>
209<tr class="private">
210 <td width="15%" align="right" valign="top" class="summary">
211 <span class="summary-type">&nbsp;</span>
212 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700213 <a name="_SYM_LINK_MESSAGE"></a><span class="summary-name">_SYM_LINK_MESSAGE</span> = <code title="'File: {0}: Is a symbolic link.'"><code class="variable-quote">'</code><code class="variable-string">File: {0}: Is a symbolic link.</code><code class="variable-quote">'</code></code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700214 </td>
215 </tr>
216<tr class="private">
217 <td width="15%" align="right" valign="top" class="summary">
218 <span class="summary-type">&nbsp;</span>
219 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700220 <a name="_IS_DIR_MESSAGE"></a><span class="summary-name">_IS_DIR_MESSAGE</span> = <code title="'{0}: Is a directory'"><code class="variable-quote">'</code><code class="variable-string">{0}: Is a directory</code><code class="variable-quote">'</code></code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700221 </td>
222 </tr>
223<tr class="private">
224 <td width="15%" align="right" valign="top" class="summary">
225 <span class="summary-type">&nbsp;</span>
226 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700227 <a href="googleapiclient._helpers-module.html#_MISSING_FILE_MESSAGE" class="summary-name" onclick="show_private();">_MISSING_FILE_MESSAGE</a> = <code title="'Cannot access {0}: No such file or directory'"><code class="variable-quote">'</code><code class="variable-string">Cannot access {0}: No such file or di</code><code class="variable-ellipsis">...</code></code>
228 </td>
229 </tr>
230<tr>
231 <td width="15%" align="right" valign="top" class="summary">
232 <span class="summary-type">&nbsp;</span>
233 </td><td class="summary">
234 <a name="__package__"></a><span class="summary-name">__package__</span> = <code title="'googleapiclient'"><code class="variable-quote">'</code><code class="variable-string">googleapiclient</code><code class="variable-quote">'</code></code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700235 </td>
236 </tr>
237</table>
238<!-- ==================== FUNCTION DETAILS ==================== -->
239<a name="section-FunctionDetails"></a>
240<table class="details" border="1" cellpadding="3"
241 cellspacing="0" width="100%" bgcolor="white">
242<tr bgcolor="#70b0f0" class="table-header">
243 <td colspan="2" class="table-header">
244 <table border="0" cellpadding="0" cellspacing="0" width="100%">
245 <tr valign="top">
246 <td align="left"><span class="table-header">Function Details</span></td>
247 <td align="right" valign="top"
248 ><span class="options">[<a href="#section-FunctionDetails"
249 class="privatelink" onclick="toggle_private();"
250 >hide private</a>]</span></td>
251 </tr>
252 </table>
253 </td>
254</tr>
255</table>
256<a name="positional"></a>
257<div>
258<table class="details" border="1" cellpadding="3"
259 cellspacing="0" width="100%" bgcolor="white">
260<tr><td>
261 <table width="100%" cellpadding="0" cellspacing="0" border="0">
262 <tr valign="top"><td>
263 <h3 class="epydoc"><span class="sig"><span class="sig-name">positional</span>(<span class="sig-arg">max_positional_args</span>)</span>
264 </h3>
265 </td><td align="right" valign="top"
266 ><span class="codelink"><a href="googleapiclient._helpers-pysrc.html#positional">source&nbsp;code</a></span>&nbsp;
267 </td>
268 </tr></table>
269
270 <pre class="literalblock">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700271A decorator to declare that only the first N arguments may be positional.
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700272
273This decorator makes it easy to support Python 3 style keyword-only
274parameters. For example, in Python 3 it is possible to write::
275
276 def fn(pos1, *, kwonly1=None, kwonly1=None):
277 ...
278
279All named parameters after ``*`` must be a keyword::
280
281 fn(10, 'kw1', 'kw2') # Raises exception.
282 fn(10, kwonly1='kw1') # Ok.
283
284Example
285^^^^^^^
286
287To define a function like above, do::
288
289 @positional(1)
290 def fn(pos1, kwonly1=None, kwonly2=None):
291 ...
292
293If no default value is provided to a keyword argument, it becomes a
294required keyword argument::
295
296 @positional(0)
297 def fn(required_kw):
298 ...
299
300This must be called with the keyword parameter::
301
302 fn() # Raises exception.
303 fn(10) # Raises exception.
304 fn(required_kw=10) # Ok.
305
306When defining instance or class methods always remember to account for
307``self`` and ``cls``::
308
309 class MyClass(object):
310
311 @positional(2)
312 def my_method(self, pos1, kwonly1=None):
313 ...
314
315 @classmethod
316 @positional(2)
317 def my_method(cls, pos1, kwonly1=None):
318 ...
319
320The positional decorator behavior is controlled by
321``_helpers.positional_parameters_enforcement``, which may be set to
322``POSITIONAL_EXCEPTION``, ``POSITIONAL_WARNING`` or
323``POSITIONAL_IGNORE`` to raise an exception, log a warning, or do
324nothing, respectively, if a declaration is violated.
325
326Args:
327 max_positional_arguments: Maximum number of positional arguments. All
328 parameters after the this index must be
329 keyword only.
330
331Returns:
332 A decorator that prevents using arguments after max_positional_args
333 from being used as positional parameters.
334
335Raises:
336 TypeError: if a key-word only argument is provided as a positional
337 parameter, but only if
338 _helpers.positional_parameters_enforcement is set to
339 POSITIONAL_EXCEPTION.
340
341</pre>
342 <dl class="fields">
343 </dl>
344</td></tr></table>
345</div>
346<a name="parse_unique_urlencoded"></a>
347<div>
348<table class="details" border="1" cellpadding="3"
349 cellspacing="0" width="100%" bgcolor="white">
350<tr><td>
351 <table width="100%" cellpadding="0" cellspacing="0" border="0">
352 <tr valign="top"><td>
353 <h3 class="epydoc"><span class="sig"><span class="sig-name">parse_unique_urlencoded</span>(<span class="sig-arg">content</span>)</span>
354 </h3>
355 </td><td align="right" valign="top"
356 ><span class="codelink"><a href="googleapiclient._helpers-pysrc.html#parse_unique_urlencoded">source&nbsp;code</a></span>&nbsp;
357 </td>
358 </tr></table>
359
360 <pre class="literalblock">
361Parses unique key-value parameters from urlencoded content.
362
363Args:
364 content: string, URL-encoded key-value pairs.
365
366Returns:
367 dict, The key-value pairs from ``content``.
368
369Raises:
370 ValueError: if one of the keys is repeated.
371
372</pre>
373 <dl class="fields">
374 </dl>
375</td></tr></table>
376</div>
377<a name="update_query_params"></a>
378<div>
379<table class="details" border="1" cellpadding="3"
380 cellspacing="0" width="100%" bgcolor="white">
381<tr><td>
382 <table width="100%" cellpadding="0" cellspacing="0" border="0">
383 <tr valign="top"><td>
384 <h3 class="epydoc"><span class="sig"><span class="sig-name">update_query_params</span>(<span class="sig-arg">uri</span>,
385 <span class="sig-arg">params</span>)</span>
386 </h3>
387 </td><td align="right" valign="top"
388 ><span class="codelink"><a href="googleapiclient._helpers-pysrc.html#update_query_params">source&nbsp;code</a></span>&nbsp;
389 </td>
390 </tr></table>
391
392 <pre class="literalblock">
393Updates a URI with new query parameters.
394
395If a given key from ``params`` is repeated in the ``uri``, then
396the URI will be considered invalid and an error will occur.
397
398If the URI is valid, then each value from ``params`` will
399replace the corresponding value in the query parameters (if
400it exists).
401
402Args:
403 uri: string, A valid URI, with potential existing query parameters.
404 params: dict, A dictionary of query parameters.
405
406Returns:
407 The same URI but with the new query parameters added.
408
409</pre>
410 <dl class="fields">
411 </dl>
412</td></tr></table>
413</div>
414<a name="_add_query_parameter"></a>
415<div class="private">
416<table class="details" border="1" cellpadding="3"
417 cellspacing="0" width="100%" bgcolor="white">
418<tr><td>
419 <table width="100%" cellpadding="0" cellspacing="0" border="0">
420 <tr valign="top"><td>
421 <h3 class="epydoc"><span class="sig"><span class="sig-name">_add_query_parameter</span>(<span class="sig-arg">url</span>,
422 <span class="sig-arg">name</span>,
423 <span class="sig-arg">value</span>)</span>
424 </h3>
425 </td><td align="right" valign="top"
426 ><span class="codelink"><a href="googleapiclient._helpers-pysrc.html#_add_query_parameter">source&nbsp;code</a></span>&nbsp;
427 </td>
428 </tr></table>
429
430 <pre class="literalblock">
431Adds a query parameter to a url.
432
433Replaces the current value if it already exists in the URL.
434
435Args:
436 url: string, url to add the query parameter to.
437 name: string, query parameter name.
438 value: string, query parameter value.
439
440Returns:
441 Updated query parameter. Does not update the url if value is None.
442
443</pre>
444 <dl class="fields">
445 </dl>
446</td></tr></table>
447</div>
448<br />
449<!-- ==================== VARIABLES DETAILS ==================== -->
450<a name="section-VariablesDetails"></a>
451<table class="details" border="1" cellpadding="3"
452 cellspacing="0" width="100%" bgcolor="white">
453<tr bgcolor="#70b0f0" class="table-header">
454 <td colspan="2" class="table-header">
455 <table border="0" cellpadding="0" cellspacing="0" width="100%">
456 <tr valign="top">
457 <td align="left"><span class="table-header">Variables Details</span></td>
458 <td align="right" valign="top"
459 ><span class="options">[<a href="#section-VariablesDetails"
460 class="privatelink" onclick="toggle_private();"
461 >hide private</a>]</span></td>
462 </tr>
463 </table>
464 </td>
465</tr>
466</table>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700467<a name="_MISSING_FILE_MESSAGE"></a>
468<div class="private">
469<table class="details" border="1" cellpadding="3"
470 cellspacing="0" width="100%" bgcolor="white">
471<tr><td>
472 <h3 class="epydoc">_MISSING_FILE_MESSAGE</h3>
473
474 <dl class="fields">
475 </dl>
476 <dl class="fields">
477 <dt>Value:</dt>
478 <dd><table><tr><td><pre class="variable">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700479<code class="variable-quote">'</code><code class="variable-string">Cannot access {0}: No such file or directory</code><code class="variable-quote">'</code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700480</pre></td></tr></table>
481</dd>
482 </dl>
483</td></tr></table>
484</div>
485<br />
486<!-- ==================== NAVIGATION BAR ==================== -->
487<table class="navbar" border="0" width="100%" cellpadding="0"
488 bgcolor="#a0c0ff" cellspacing="0">
489 <tr valign="middle">
490 <!-- Home link -->
491 <th>&nbsp;&nbsp;&nbsp;<a
492 href="googleapiclient-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
493
494 <!-- Tree link -->
495 <th>&nbsp;&nbsp;&nbsp;<a
496 href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
497
498 <!-- Index link -->
499 <th>&nbsp;&nbsp;&nbsp;<a
500 href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
501
502 <!-- Help link -->
503 <th>&nbsp;&nbsp;&nbsp;<a
504 href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
505
506 <th class="navbar" width="100%"></th>
507 </tr>
508</table>
509<table border="0" cellpadding="0" cellspacing="0" width="100%%">
510 <tr>
511 <td align="left" class="footer">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700512 Generated by Epydoc 3.0.1 on Fri Oct 2 20:46:22 2020
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700513 </td>
514 <td align="right" class="footer">
515 <a target="mainFrame" href="http://epydoc.sourceforge.net"
516 >http://epydoc.sourceforge.net</a>
517 </td>
518 </tr>
519</table>
520
521<script type="text/javascript">
522 <!--
523 // Private objects are initially displayed (because if
524 // javascript is turned off then we want them to be
525 // visible); but by default, we want to hide them. So hide
526 // them unless we have a cookie that says to show them.
527 checkCookie();
528 // -->
529</script>
530</body>
531</html>