Skip to content
This repository was archived by the owner on Nov 22, 2024. It is now read-only.

Commit 797b90f

Browse files
mahtinmahtin
committed
Added --raw mode examples
1 parent c1ead41 commit 797b90f

2 files changed

Lines changed: 247 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 118 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ The Cloudflare API can be found [here](https://api.cloudflare.com/).
3838
Each API call is provided via a similarly named function within the _CloudFlare_ class.
3939
A full list is provided below.
4040

41+
## Example code
42+
43+
All example code is available on GitHub (see [package](https://github.com/cloudflare/python-cloudflare) in the [examples](https://github.com/cloudflare/python-cloudflare/tree/master/examples) folder.
44+
4145
## Getting Started
4246

4347
A very simple listing of zones within your account; including the IPv6 status of the zone.
@@ -165,9 +169,75 @@ The *extras* values are used when adding API calls outside of the core codebase.
165169
Technically, this is only useful for internal testing within Cloudflare.
166170
You can leave *extras* in the configuration with a blank value (or omit the option variable fully).
167171

172+
## Exceptions and return values
173+
174+
The response is build from the JSON in the API call.
175+
It contains the **results** values; but does not contain the paging values.
176+
177+
You can return all the paging values by calling the class with raw=True. Here's an example without paging.
178+
179+
```python
180+
#!/usr/bin/env python
181+
182+
import json
183+
import CloudFlare
184+
185+
def main():
186+
cf = CloudFlare.CloudFlare()
187+
zones = cf.zones.get(params={'per_page':5})
188+
print len(zones)
189+
190+
if __name__ == '__main__':
191+
main()
192+
```
193+
194+
The results are as follows.
195+
196+
```
197+
5
198+
```
199+
200+
When you add the raw option; the APIs full structure is returned. This means the paging values can be seen.
201+
202+
```python
203+
#!/usr/bin/env python
204+
205+
import json
206+
import CloudFlare
207+
208+
def main():
209+
cf = CloudFlare.CloudFlare(raw=True)
210+
zones = cf.zones.get(params={'per_page':5})
211+
print zones.length()
212+
print json.dumps(zones, indent=4, sort_keys=True)
213+
214+
if __name__ == '__main__':
215+
main()
216+
```
217+
218+
This produces.
219+
220+
```
221+
5
222+
{
223+
"result": [
224+
...
225+
],
226+
"result_info": {
227+
"count": 5,
228+
"page": 1,
229+
"per_page": 5,
230+
"total_count": 31,
231+
"total_pages": 7
232+
}
233+
}
234+
```
235+
236+
A full example of paging is provided below.
237+
168238
## Included example code
169239

170-
The *examples* folder contains many examples in both simple and verbose formats.
240+
The [examples](https://github.com/cloudflare/python-cloudflare/tree/master/examples) folder contains many examples in both simple and verbose formats.
171241

172242
## A DNS zone code example
173243

@@ -205,13 +275,13 @@ All API calls can be called from the command line.
205275
The command will convert domain names on-the-fly into zone_identifier's.
206276

207277
```bash
208-
$ cli4 [-h|--help] [-v|--verbose] [-q|--quiet] [--get|--patch|--post|-put|--delete] [item=value ...] /command...
278+
$ cli4 [-V|--version] [-h|--help] [-v|--verbose] [-q|--quiet] [-j|--json] [-y|--yaml] [-r|--raw] [--get|--patch|--post|-put|--delete] [item=value ...] /command...
209279
```
210280

211281
For API calls that need a set of date or parameters passed there is a item=value format.
212282
If you want a numeric value passed, then _==_ can be used to force the value to be treated as a numeric value.
213283

214-
The output from the CLI command is in json format (and human readable).
284+
The output from the CLI command is in JSON or YAML format (and human readable).
215285

216286
### Simple CLI examples
217287

@@ -295,6 +365,51 @@ $ cli4 /zones/:example.com/available_plans | jq -c '.[]|{"id":.id,"name":.name}'
295365
$
296366
```
297367

368+
### Paging CLI examples
369+
370+
The **--raw** command provides access to the paging returned values.
371+
See the API documentation for all the info.
372+
Here's an example of how to page thru a list of zones (it's included in the examples folder as **example_paging_thru_zones.sh**).
373+
374+
```bash
375+
:
376+
tmp=/tmp/$$_
377+
trap "rm ${tmp}; exit 0" 0 1 2 15
378+
PAGE=0
379+
while true
380+
do
381+
cli4 --raw per_page=5 page=${PAGE} /zones > ${tmp}
382+
domains=`jq -c '.|.result|.[]|.name' < ${tmp} | tr -d '"'`
383+
result_info=`jq -c '.|.result_info' < ${tmp}`
384+
COUNT=` echo "${result_info}" | jq .count`
385+
PAGE=` echo "${result_info}" | jq .page`
386+
PER_PAGE=` echo "${result_info}" | jq .per_page`
387+
TOTAL_COUNT=`echo "${result_info}" | jq .total_count`
388+
TOTAL_PAGES=`echo "${result_info}" | jq .total_pages`
389+
echo COUNT=${COUNT} PAGE=${PAGE} PER_PAGE=${PER_PAGE} TOTAL_COUNT=${TOTAL_COUNT} TOTAL_PAGES=${TOTAL_PAGES} -- ${domains}
390+
if [ "${PAGE}" == "${TOTAL_PAGES}" ]
391+
then
392+
## last section
393+
break
394+
fi
395+
# grab the next page
396+
PAGE=`expr ${PAGE} + 1`
397+
done
398+
```
399+
400+
It produces the following results.
401+
402+
```
403+
COUNT=5 PAGE=1 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- accumsan.example auctor.example consectetur.example dapibus.example elementum.example
404+
COUNT=5 PAGE=2 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- felis.example iaculis.example ipsum.example justo.example lacus.example
405+
COUNT=5 PAGE=3 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- lectus.example lobortis.example maximus.example morbi.example pharetra.example
406+
COUNT=5 PAGE=4 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- porttitor.example potenti.example pretium.example purus.example quisque.example
407+
COUNT=5 PAGE=5 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- sagittis.example semper.example sollicitudin.example suspendisse.example tortor.example
408+
COUNT=1 PAGE=7 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- varius.example vehicula.example velit.example velit.example vitae.example
409+
COUNT=5 PAGE=6 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- vivamus.example
410+
```
411+
412+
298413
### DNSSEC CLI examples
299414

300415
```bash

‎README.rst‎

Lines changed: 129 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,14 @@ The Cloudflare API can be found `here <https://api.cloudflare.com/>`__.
4747
Each API call is provided via a similarly named function within the
4848
*CloudFlare* class. A full list is provided below.
4949

50+
Example code
51+
------------
52+
53+
All example code is available on GitHub (see
54+
`package <https://github.com/cloudflare/python-cloudflare>`__ in the
55+
`examples <https://github.com/cloudflare/python-cloudflare/tree/master/examples>`__
56+
folder.
57+
5058
Getting Started
5159
---------------
5260

@@ -188,11 +196,81 @@ codebase. Technically, this is only useful for internal testing within
188196
Cloudflare. You can leave *extras* in the configuration with a blank
189197
value (or omit the option variable fully).
190198

199+
Exceptions and return values
200+
----------------------------
201+
202+
The response is build from the JSON in the API call. It contains the
203+
**results** values; but does not contain the paging values.
204+
205+
You can return all the paging values by calling the class with raw=True.
206+
Here's an example without paging.
207+
208+
.. code:: python
209+
210+
#!/usr/bin/env python
211+
212+
import json
213+
import CloudFlare
214+
215+
def main():
216+
cf = CloudFlare.CloudFlare()
217+
zones = cf.zones.get(params={'per_page':5})
218+
print len(zones)
219+
220+
if __name__ == '__main__':
221+
main()
222+
223+
The results are as follows.
224+
225+
::
226+
227+
5
228+
229+
When you add the raw option; the APIs full structure is returned. This
230+
means the paging values can be seen.
231+
232+
.. code:: python
233+
234+
#!/usr/bin/env python
235+
236+
import json
237+
import CloudFlare
238+
239+
def main():
240+
cf = CloudFlare.CloudFlare(raw=True)
241+
zones = cf.zones.get(params={'per_page':5})
242+
print zones.length()
243+
print json.dumps(zones, indent=4, sort_keys=True)
244+
245+
if __name__ == '__main__':
246+
main()
247+
248+
This produces.
249+
250+
::
251+
252+
5
253+
{
254+
"result": [
255+
...
256+
],
257+
"result_info": {
258+
"count": 5,
259+
"page": 1,
260+
"per_page": 5,
261+
"total_count": 31,
262+
"total_pages": 7
263+
}
264+
}
265+
266+
A full example of paging is provided below.
267+
191268
Included example code
192269
---------------------
193270

194-
The *examples* folder contains many examples in both simple and verbose
195-
formats.
271+
The
272+
`examples <https://github.com/cloudflare/python-cloudflare/tree/master/examples>`__
273+
folder contains many examples in both simple and verbose formats.
196274

197275
A DNS zone code example
198276
-----------------------
@@ -233,13 +311,14 @@ convert domain names on-the-fly into zone\_identifier's.
233311

234312
.. code:: bash
235313
236-
$ cli4 [-h|--help] [-v|--verbose] [-q|--quiet] [--get|--patch|--post|-put|--delete] [item=value ...] /command...
314+
$ cli4 [-V|--version] [-h|--help] [-v|--verbose] [-q|--quiet] [-j|--json] [-y|--yaml] [-r|--raw] [--get|--patch|--post|-put|--delete] [item=value ...] /command...
237315
238316
For API calls that need a set of date or parameters passed there is a
239317
item=value format. If you want a numeric value passed, then *==* can be
240318
used to force the value to be treated as a numeric value.
241319

242-
The output from the CLI command is in json format (and human readable).
320+
The output from the CLI command is in JSON or YAML format (and human
321+
readable).
243322

244323
Simple CLI examples
245324
~~~~~~~~~~~~~~~~~~~
@@ -326,6 +405,52 @@ A somewhat useful listing of available plans for a specific zone.
326405
{"id":"0feeeeeeeeeeeeeeeeeeeeeeeeeeeeee","name":"Free Website"}
327406
$
328407
408+
Paging CLI examples
409+
~~~~~~~~~~~~~~~~~~~
410+
411+
The **--raw** command provides access to the paging returned values. See
412+
the API documentation for all the info. Here's an example of how to page
413+
thru a list of zones (it's included in the examples folder as
414+
**example\_paging\_thru\_zones.sh**).
415+
416+
.. code:: bash
417+
418+
:
419+
tmp=/tmp/$$_
420+
trap "rm ${tmp}; exit 0" 0 1 2 15
421+
PAGE=0
422+
while true
423+
do
424+
cli4 --raw per_page=5 page=${PAGE} /zones > ${tmp}
425+
domains=`jq -c '.|.result|.[]|.name' < ${tmp} | tr -d '"'`
426+
result_info=`jq -c '.|.result_info' < ${tmp}`
427+
COUNT=` echo "${result_info}" | jq .count`
428+
PAGE=` echo "${result_info}" | jq .page`
429+
PER_PAGE=` echo "${result_info}" | jq .per_page`
430+
TOTAL_COUNT=`echo "${result_info}" | jq .total_count`
431+
TOTAL_PAGES=`echo "${result_info}" | jq .total_pages`
432+
echo COUNT=${COUNT} PAGE=${PAGE} PER_PAGE=${PER_PAGE} TOTAL_COUNT=${TOTAL_COUNT} TOTAL_PAGES=${TOTAL_PAGES} -- ${domains}
433+
if [ "${PAGE}" == "${TOTAL_PAGES}" ]
434+
then
435+
## last section
436+
break
437+
fi
438+
# grab the next page
439+
PAGE=`expr ${PAGE} + 1`
440+
done
441+
442+
It produces the following results.
443+
444+
::
445+
446+
COUNT=5 PAGE=1 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- accumsan.example auctor.example consectetur.example dapibus.example elementum.example
447+
COUNT=5 PAGE=2 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- felis.example iaculis.example ipsum.example justo.example lacus.example
448+
COUNT=5 PAGE=3 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- lectus.example lobortis.example maximus.example morbi.example pharetra.example
449+
COUNT=5 PAGE=4 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- porttitor.example potenti.example pretium.example purus.example quisque.example
450+
COUNT=5 PAGE=5 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- sagittis.example semper.example sollicitudin.example suspendisse.example tortor.example
451+
COUNT=1 PAGE=7 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- varius.example vehicula.example velit.example velit.example vitae.example
452+
COUNT=5 PAGE=6 PER_PAGE=5 TOTAL_COUNT=31 TOTAL_PAGES=7 -- vivamus.example
453+
329454
DNSSEC CLI examples
330455
~~~~~~~~~~~~~~~~~~~
331456

0 commit comments

Comments
 (0)