blob: 687537547b816ebf0189212d1d6bfded9e5382af [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>
59<pre class="literalblock">
60Helper functions for commonly used utilities.
61
62</pre>
63
64<!-- ==================== FUNCTIONS ==================== -->
65<a name="section-Functions"></a>
66<table class="summary" border="1" cellpadding="3"
67 cellspacing="0" width="100%" bgcolor="white">
68<tr bgcolor="#70b0f0" class="table-header">
69 <td colspan="2" class="table-header">
70 <table border="0" cellpadding="0" cellspacing="0" width="100%">
71 <tr valign="top">
72 <td align="left"><span class="table-header">Functions</span></td>
73 <td align="right" valign="top"
74 ><span class="options">[<a href="#section-Functions"
75 class="privatelink" onclick="toggle_private();"
76 >hide private</a>]</span></td>
77 </tr>
78 </table>
79 </td>
80</tr>
81<tr>
82 <td width="15%" align="right" valign="top" class="summary">
83 <span class="summary-type">&nbsp;</span>
84 </td><td class="summary">
85 <table width="100%" cellpadding="0" cellspacing="0" border="0">
86 <tr>
87 <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 />
88 A decorator to declare that only the first N arguments my be positional.</td>
89 <td align="right" valign="top">
90 <span class="codelink"><a href="googleapiclient._helpers-pysrc.html#positional">source&nbsp;code</a></span>
91
92 </td>
93 </tr>
94 </table>
95
96 </td>
97 </tr>
98<tr>
99 <td width="15%" align="right" valign="top" class="summary">
100 <span class="summary-type">&nbsp;</span>
101 </td><td class="summary">
102 <table width="100%" cellpadding="0" cellspacing="0" border="0">
103 <tr>
104 <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 />
105 Parses unique key-value parameters from urlencoded content.</td>
106 <td align="right" valign="top">
107 <span class="codelink"><a href="googleapiclient._helpers-pysrc.html#parse_unique_urlencoded">source&nbsp;code</a></span>
108
109 </td>
110 </tr>
111 </table>
112
113 </td>
114 </tr>
115<tr>
116 <td width="15%" align="right" valign="top" class="summary">
117 <span class="summary-type">&nbsp;</span>
118 </td><td class="summary">
119 <table width="100%" cellpadding="0" cellspacing="0" border="0">
120 <tr>
121 <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>,
122 <span class="summary-sig-arg">params</span>)</span><br />
123 Updates a URI with new query parameters.</td>
124 <td align="right" valign="top">
125 <span class="codelink"><a href="googleapiclient._helpers-pysrc.html#update_query_params">source&nbsp;code</a></span>
126
127 </td>
128 </tr>
129 </table>
130
131 </td>
132 </tr>
133<tr class="private">
134 <td width="15%" align="right" valign="top" class="summary">
135 <span class="summary-type">&nbsp;</span>
136 </td><td class="summary">
137 <table width="100%" cellpadding="0" cellspacing="0" border="0">
138 <tr>
139 <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>,
140 <span class="summary-sig-arg">name</span>,
141 <span class="summary-sig-arg">value</span>)</span><br />
142 Adds a query parameter to a url.</td>
143 <td align="right" valign="top">
144 <span class="codelink"><a href="googleapiclient._helpers-pysrc.html#_add_query_parameter">source&nbsp;code</a></span>
145
146 </td>
147 </tr>
148 </table>
149
150 </td>
151 </tr>
152</table>
153<!-- ==================== VARIABLES ==================== -->
154<a name="section-Variables"></a>
155<table class="summary" border="1" cellpadding="3"
156 cellspacing="0" width="100%" bgcolor="white">
157<tr bgcolor="#70b0f0" class="table-header">
158 <td colspan="2" class="table-header">
159 <table border="0" cellpadding="0" cellspacing="0" width="100%">
160 <tr valign="top">
161 <td align="left"><span class="table-header">Variables</span></td>
162 <td align="right" valign="top"
163 ><span class="options">[<a href="#section-Variables"
164 class="privatelink" onclick="toggle_private();"
165 >hide private</a>]</span></td>
166 </tr>
167 </table>
168 </td>
169</tr>
170<tr>
171 <td width="15%" align="right" valign="top" class="summary">
172 <span class="summary-type">&nbsp;</span>
173 </td><td class="summary">
174 <a name="logger"></a><span class="summary-name">logger</span> = <code title="logging.getLogger(__name__)">logging.getLogger(__name__)</code>
175 </td>
176 </tr>
177<tr>
178 <td width="15%" align="right" valign="top" class="summary">
179 <span class="summary-type">&nbsp;</span>
180 </td><td class="summary">
Dan O'Mearadd494642020-05-01 07:42:23 -0700181 <a name="POSITIONAL_WARNING"></a><span class="summary-name">POSITIONAL_WARNING</span> = <code title="&quot;WARNING&quot;">&quot;WARNING&quot;</code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700182 </td>
183 </tr>
184<tr>
185 <td width="15%" align="right" valign="top" class="summary">
186 <span class="summary-type">&nbsp;</span>
187 </td><td class="summary">
Dan O'Mearadd494642020-05-01 07:42:23 -0700188 <a name="POSITIONAL_EXCEPTION"></a><span class="summary-name">POSITIONAL_EXCEPTION</span> = <code title="&quot;EXCEPTION&quot;">&quot;EXCEPTION&quot;</code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700189 </td>
190 </tr>
191<tr>
192 <td width="15%" align="right" valign="top" class="summary">
193 <span class="summary-type">&nbsp;</span>
194 </td><td class="summary">
Dan O'Mearadd494642020-05-01 07:42:23 -0700195 <a name="POSITIONAL_IGNORE"></a><span class="summary-name">POSITIONAL_IGNORE</span> = <code title="&quot;IGNORE&quot;">&quot;IGNORE&quot;</code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700196 </td>
197 </tr>
198<tr>
199 <td width="15%" align="right" valign="top" class="summary">
200 <span class="summary-type">&nbsp;</span>
201 </td><td class="summary">
202 <a href="googleapiclient._helpers-module.html#POSITIONAL_SET" class="summary-name">POSITIONAL_SET</a> = <code title="frozenset([POSITIONAL_WARNING, POSITIONAL_EXCEPTION, POSITIONAL_IGNORE\
203])">frozenset([POSITIONAL_WARNING, POSITIONAL_EXC<code class="variable-ellipsis">...</code></code>
204 </td>
205 </tr>
206<tr>
207 <td width="15%" align="right" valign="top" class="summary">
208 <span class="summary-type">&nbsp;</span>
209 </td><td class="summary">
Dan O'Mearadd494642020-05-01 07:42:23 -0700210 <a name="positional_parameters_enforcement"></a><span class="summary-name">positional_parameters_enforcement</span> = <code title="&quot;WARNING&quot;">&quot;WARNING&quot;</code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700211 </td>
212 </tr>
213<tr class="private">
214 <td width="15%" align="right" valign="top" class="summary">
215 <span class="summary-type">&nbsp;</span>
216 </td><td class="summary">
Dan O'Mearadd494642020-05-01 07:42:23 -0700217 <a name="_SYM_LINK_MESSAGE"></a><span class="summary-name">_SYM_LINK_MESSAGE</span> = <code title="&quot;File: {0}: Is a symbolic link.&quot;">&quot;File: {0}: Is a symbolic link.&quot;</code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700218 </td>
219 </tr>
220<tr class="private">
221 <td width="15%" align="right" valign="top" class="summary">
222 <span class="summary-type">&nbsp;</span>
223 </td><td class="summary">
Dan O'Mearadd494642020-05-01 07:42:23 -0700224 <a name="_IS_DIR_MESSAGE"></a><span class="summary-name">_IS_DIR_MESSAGE</span> = <code title="&quot;{0}: Is a directory&quot;">&quot;{0}: Is a directory&quot;</code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700225 </td>
226 </tr>
227<tr class="private">
228 <td width="15%" align="right" valign="top" class="summary">
229 <span class="summary-type">&nbsp;</span>
230 </td><td class="summary">
Dan O'Mearadd494642020-05-01 07:42:23 -0700231 <a href="googleapiclient._helpers-module.html#_MISSING_FILE_MESSAGE" class="summary-name" onclick="show_private();">_MISSING_FILE_MESSAGE</a> = <code title="&quot;Cannot access {0}: No such file or directory&quot;">&quot;Cannot access {0}: No such file or di<code class="variable-ellipsis">...</code></code>
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700232 </td>
233 </tr>
234</table>
235<!-- ==================== FUNCTION DETAILS ==================== -->
236<a name="section-FunctionDetails"></a>
237<table class="details" border="1" cellpadding="3"
238 cellspacing="0" width="100%" bgcolor="white">
239<tr bgcolor="#70b0f0" class="table-header">
240 <td colspan="2" class="table-header">
241 <table border="0" cellpadding="0" cellspacing="0" width="100%">
242 <tr valign="top">
243 <td align="left"><span class="table-header">Function Details</span></td>
244 <td align="right" valign="top"
245 ><span class="options">[<a href="#section-FunctionDetails"
246 class="privatelink" onclick="toggle_private();"
247 >hide private</a>]</span></td>
248 </tr>
249 </table>
250 </td>
251</tr>
252</table>
253<a name="positional"></a>
254<div>
255<table class="details" border="1" cellpadding="3"
256 cellspacing="0" width="100%" bgcolor="white">
257<tr><td>
258 <table width="100%" cellpadding="0" cellspacing="0" border="0">
259 <tr valign="top"><td>
260 <h3 class="epydoc"><span class="sig"><span class="sig-name">positional</span>(<span class="sig-arg">max_positional_args</span>)</span>
261 </h3>
262 </td><td align="right" valign="top"
263 ><span class="codelink"><a href="googleapiclient._helpers-pysrc.html#positional">source&nbsp;code</a></span>&nbsp;
264 </td>
265 </tr></table>
266
267 <pre class="literalblock">
268A decorator to declare that only the first N arguments my be positional.
269
270This decorator makes it easy to support Python 3 style keyword-only
271parameters. For example, in Python 3 it is possible to write::
272
273 def fn(pos1, *, kwonly1=None, kwonly1=None):
274 ...
275
276All named parameters after ``*`` must be a keyword::
277
278 fn(10, 'kw1', 'kw2') # Raises exception.
279 fn(10, kwonly1='kw1') # Ok.
280
281Example
282^^^^^^^
283
284To define a function like above, do::
285
286 @positional(1)
287 def fn(pos1, kwonly1=None, kwonly2=None):
288 ...
289
290If no default value is provided to a keyword argument, it becomes a
291required keyword argument::
292
293 @positional(0)
294 def fn(required_kw):
295 ...
296
297This must be called with the keyword parameter::
298
299 fn() # Raises exception.
300 fn(10) # Raises exception.
301 fn(required_kw=10) # Ok.
302
303When defining instance or class methods always remember to account for
304``self`` and ``cls``::
305
306 class MyClass(object):
307
308 @positional(2)
309 def my_method(self, pos1, kwonly1=None):
310 ...
311
312 @classmethod
313 @positional(2)
314 def my_method(cls, pos1, kwonly1=None):
315 ...
316
317The positional decorator behavior is controlled by
318``_helpers.positional_parameters_enforcement``, which may be set to
319``POSITIONAL_EXCEPTION``, ``POSITIONAL_WARNING`` or
320``POSITIONAL_IGNORE`` to raise an exception, log a warning, or do
321nothing, respectively, if a declaration is violated.
322
323Args:
324 max_positional_arguments: Maximum number of positional arguments. All
325 parameters after the this index must be
326 keyword only.
327
328Returns:
329 A decorator that prevents using arguments after max_positional_args
330 from being used as positional parameters.
331
332Raises:
333 TypeError: if a key-word only argument is provided as a positional
334 parameter, but only if
335 _helpers.positional_parameters_enforcement is set to
336 POSITIONAL_EXCEPTION.
337
338</pre>
339 <dl class="fields">
340 </dl>
341</td></tr></table>
342</div>
343<a name="parse_unique_urlencoded"></a>
344<div>
345<table class="details" border="1" cellpadding="3"
346 cellspacing="0" width="100%" bgcolor="white">
347<tr><td>
348 <table width="100%" cellpadding="0" cellspacing="0" border="0">
349 <tr valign="top"><td>
350 <h3 class="epydoc"><span class="sig"><span class="sig-name">parse_unique_urlencoded</span>(<span class="sig-arg">content</span>)</span>
351 </h3>
352 </td><td align="right" valign="top"
353 ><span class="codelink"><a href="googleapiclient._helpers-pysrc.html#parse_unique_urlencoded">source&nbsp;code</a></span>&nbsp;
354 </td>
355 </tr></table>
356
357 <pre class="literalblock">
358Parses unique key-value parameters from urlencoded content.
359
360Args:
361 content: string, URL-encoded key-value pairs.
362
363Returns:
364 dict, The key-value pairs from ``content``.
365
366Raises:
367 ValueError: if one of the keys is repeated.
368
369</pre>
370 <dl class="fields">
371 </dl>
372</td></tr></table>
373</div>
374<a name="update_query_params"></a>
375<div>
376<table class="details" border="1" cellpadding="3"
377 cellspacing="0" width="100%" bgcolor="white">
378<tr><td>
379 <table width="100%" cellpadding="0" cellspacing="0" border="0">
380 <tr valign="top"><td>
381 <h3 class="epydoc"><span class="sig"><span class="sig-name">update_query_params</span>(<span class="sig-arg">uri</span>,
382 <span class="sig-arg">params</span>)</span>
383 </h3>
384 </td><td align="right" valign="top"
385 ><span class="codelink"><a href="googleapiclient._helpers-pysrc.html#update_query_params">source&nbsp;code</a></span>&nbsp;
386 </td>
387 </tr></table>
388
389 <pre class="literalblock">
390Updates a URI with new query parameters.
391
392If a given key from ``params`` is repeated in the ``uri``, then
393the URI will be considered invalid and an error will occur.
394
395If the URI is valid, then each value from ``params`` will
396replace the corresponding value in the query parameters (if
397it exists).
398
399Args:
400 uri: string, A valid URI, with potential existing query parameters.
401 params: dict, A dictionary of query parameters.
402
403Returns:
404 The same URI but with the new query parameters added.
405
406</pre>
407 <dl class="fields">
408 </dl>
409</td></tr></table>
410</div>
411<a name="_add_query_parameter"></a>
412<div class="private">
413<table class="details" border="1" cellpadding="3"
414 cellspacing="0" width="100%" bgcolor="white">
415<tr><td>
416 <table width="100%" cellpadding="0" cellspacing="0" border="0">
417 <tr valign="top"><td>
418 <h3 class="epydoc"><span class="sig"><span class="sig-name">_add_query_parameter</span>(<span class="sig-arg">url</span>,
419 <span class="sig-arg">name</span>,
420 <span class="sig-arg">value</span>)</span>
421 </h3>
422 </td><td align="right" valign="top"
423 ><span class="codelink"><a href="googleapiclient._helpers-pysrc.html#_add_query_parameter">source&nbsp;code</a></span>&nbsp;
424 </td>
425 </tr></table>
426
427 <pre class="literalblock">
428Adds a query parameter to a url.
429
430Replaces the current value if it already exists in the URL.
431
432Args:
433 url: string, url to add the query parameter to.
434 name: string, query parameter name.
435 value: string, query parameter value.
436
437Returns:
438 Updated query parameter. Does not update the url if value is None.
439
440</pre>
441 <dl class="fields">
442 </dl>
443</td></tr></table>
444</div>
445<br />
446<!-- ==================== VARIABLES DETAILS ==================== -->
447<a name="section-VariablesDetails"></a>
448<table class="details" border="1" cellpadding="3"
449 cellspacing="0" width="100%" bgcolor="white">
450<tr bgcolor="#70b0f0" class="table-header">
451 <td colspan="2" class="table-header">
452 <table border="0" cellpadding="0" cellspacing="0" width="100%">
453 <tr valign="top">
454 <td align="left"><span class="table-header">Variables Details</span></td>
455 <td align="right" valign="top"
456 ><span class="options">[<a href="#section-VariablesDetails"
457 class="privatelink" onclick="toggle_private();"
458 >hide private</a>]</span></td>
459 </tr>
460 </table>
461 </td>
462</tr>
463</table>
464<a name="POSITIONAL_SET"></a>
465<div>
466<table class="details" border="1" cellpadding="3"
467 cellspacing="0" width="100%" bgcolor="white">
468<tr><td>
469 <h3 class="epydoc">POSITIONAL_SET</h3>
470
471 <dl class="fields">
472 </dl>
473 <dl class="fields">
474 <dt>Value:</dt>
475 <dd><table><tr><td><pre class="variable">
476frozenset([POSITIONAL_WARNING, POSITIONAL_EXCEPTION, POSITIONAL_IGNORE<span class="variable-linewrap"><img src="crarr.png" alt="\" /></span>
477])
478</pre></td></tr></table>
479</dd>
480 </dl>
481</td></tr></table>
482</div>
483<a name="_MISSING_FILE_MESSAGE"></a>
484<div class="private">
485<table class="details" border="1" cellpadding="3"
486 cellspacing="0" width="100%" bgcolor="white">
487<tr><td>
488 <h3 class="epydoc">_MISSING_FILE_MESSAGE</h3>
489
490 <dl class="fields">
491 </dl>
492 <dl class="fields">
493 <dt>Value:</dt>
494 <dd><table><tr><td><pre class="variable">
Dan O'Mearadd494642020-05-01 07:42:23 -0700495&quot;Cannot access {0}: No such file or directory&quot;
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700496</pre></td></tr></table>
497</dd>
498 </dl>
499</td></tr></table>
500</div>
501<br />
502<!-- ==================== NAVIGATION BAR ==================== -->
503<table class="navbar" border="0" width="100%" cellpadding="0"
504 bgcolor="#a0c0ff" cellspacing="0">
505 <tr valign="middle">
506 <!-- Home link -->
507 <th>&nbsp;&nbsp;&nbsp;<a
508 href="googleapiclient-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
509
510 <!-- Tree link -->
511 <th>&nbsp;&nbsp;&nbsp;<a
512 href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
513
514 <!-- Index link -->
515 <th>&nbsp;&nbsp;&nbsp;<a
516 href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
517
518 <!-- Help link -->
519 <th>&nbsp;&nbsp;&nbsp;<a
520 href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
521
522 <th class="navbar" width="100%"></th>
523 </tr>
524</table>
525<table border="0" cellpadding="0" cellspacing="0" width="100%%">
526 <tr>
527 <td align="left" class="footer">
Dan O'Mearadd494642020-05-01 07:42:23 -0700528 Generated by Epydoc 3.0.1 on Thu Apr 30 17:06:05 2020
Bu Sun Kim02bae1c2019-06-14 13:33:59 -0700529 </td>
530 <td align="right" class="footer">
531 <a target="mainFrame" href="http://epydoc.sourceforge.net"
532 >http://epydoc.sourceforge.net</a>
533 </td>
534 </tr>
535</table>
536
537<script type="text/javascript">
538 <!--
539 // Private objects are initially displayed (because if
540 // javascript is turned off then we want them to be
541 // visible); but by default, we want to hide them. So hide
542 // them unless we have a cookie that says to show them.
543 checkCookie();
544 // -->
545</script>
546</body>
547</html>