Skip to content
This repository has been archived by the owner on May 7, 2024. It is now read-only.

Commit

Permalink
Added Python3.x documentation. Renamed files with dashes to underscores.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mahtin
mahtin committed Jun 11, 2016
1 parent 2e2f856 commit 9e850db
Show file tree
Hide file tree
Showing 14 changed files with 134 additions and 106 deletions.
189 changes: 102 additions & 87 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,32 +2,36 @@

## Installation

Two methods are provided to install this software. Use PyPi (see [package](https://pypi.python.org/pypi/cloudflare) details) or GitHub (see [package](https://github.com/cloudflare/python-cloudflare) details).
Two methods are provided to install this software.
Use PyPi (see [package](https://pypi.python.org/pypi/cloudflare) details) or GitHub (see [package](https://github.com/cloudflare/python-cloudflare) details).

### Via PyPI

```bash
$ sudo pip install cloudflare
$
$ sudo pip install cloudflare
$
```

Yes - that simple! (the sudo may not be needed in some cases).

### Via github

```bash
$ git clone https://github.com/cloudflare/python-cloudflare
$ cd python-cloudflare
$ ./setup.py build
$ sudo ./setup.py install
$
$ git clone https://github.com/cloudflare/python-cloudflare
$ cd python-cloudflare
$ ./setup.py build
$ sudo ./setup.py install
$
```

Or whatever variance of that you want to use.
There is a Makefile included.

## CloudFlare API version 4

The CloudFlare API can be found [here](https://api.cloudflare.com/). Each API call is provided via a similarly named function within the _CloudFlare_ class. A full list is provided below.
The CloudFlare API can be found [here](https://api.cloudflare.com/).
Each API call is provided via a similarly named function within the _CloudFlare_ class.
A full list is provided below.

## Getting Started

Expand All @@ -37,19 +41,19 @@ A very simple listing of zones within your account; including the IPv6 status of
import CloudFlare

def main():
cf = CloudFlare.CloudFlare()
zones = cf.zones.get(params = {'per_page':50})
for zone in zones:
zone_name = zone['name']
zone_id = zone['id']
settings_ipv6 = cf.zones.settings.ipv6.get(zone_id)
ipv6_status = settings_ipv6['value']
settings_ssl = cf.zones.settings.ssl.get(zone_id)
ssl_status = settings_ssl['value']
print zone_id, ssl_status, ipv6_status, zone_name
cf = CloudFlare.CloudFlare()
zones = cf.zones.get(params = {'per_page':50})
for zone in zones:
zone_name = zone['name']
zone_id = zone['id']
settings_ipv6 = cf.zones.settings.ipv6.get(zone_id)
ipv6_status = settings_ipv6['value']
settings_ssl = cf.zones.settings.ssl.get(zone_id)
ssl_status = settings_ssl['value']
print zone_id, ssl_status, ipv6_status, zone_name

if __name__ == '__main__':
main()
main()
```

A more complex example follows.
Expand All @@ -59,43 +63,43 @@ import sys
import CloudFlare

def main():
zone_name = 'example.com'
zone_name = 'example.com'

cf = CloudFlare.CloudFlare()
cf = CloudFlare.CloudFlare()

# query for the zone name and expect only one value back
try:
zones = cf.zones.get(params = {'name':zone_name,'per_page':1})
except CloudFlare.CloudFlareAPIError as e:
exit('/zones.get %d %s - api call failed' % (e, e))
except Exception as e:
exit('/zones.get - %s - api call failed' % (e))
# query for the zone name and expect only one value back
try:
zones = cf.zones.get(params = {'name':zone_name,'per_page':1})
except CloudFlare.CloudFlareAPIError as e:
exit('/zones.get %d %s - api call failed' % (e, e))
except Exception as e:
exit('/zones.get - %s - api call failed' % (e))

# extract the zone_id which is needed to process that zone
zone = zones[0]
zone_id = zone['id']
# extract the zone_id which is needed to process that zone
zone = zones[0]
zone_id = zone['id']

# request the DNS records from that zone
try:
dns_records = cf.zones.dns_records.get(zone_id)
except CloudFlare.CloudFlareAPIError as e:
exit('/zones/dns_records.get %d %s - api call failed' % (e, e))
# request the DNS records from that zone
try:
dns_records = cf.zones.dns_records.get(zone_id)
except CloudFlare.CloudFlareAPIError as e:
exit('/zones/dns_records.get %d %s - api call failed' % (e, e))

# print the results - first the zone name
print zone_id, zone_name
# print the results - first the zone name
print zone_id, zone_name

# then all the DNS records for that zone
for dns_record in dns_records:
r_name = dns_record['name']
r_type = dns_record['type']
r_value = dns_record['content']
r_id = dns_record['id']
print '\t', r_id, r_name, r_type, r_value
# then all the DNS records for that zone
for dns_record in dns_records:
r_name = dns_record['name']
r_type = dns_record['type']
r_value = dns_record['content']
r_id = dns_record['id']
print '\t', r_id, r_name, r_type, r_value

exit(0)
exit(0)

if __name__ == '__main__':
main()
main()
```

## Providing CloudFlare Username and API Key
Expand All @@ -121,7 +125,7 @@ $
### Using configuration file to store email and keys

```bash
$ cat ~/.cloudflare/cloudflare.cfg
$ cat ~/.cloudflare/cloudflare.cfg
[CloudFlare]
email = [email protected]
token = 00000000000000000000000000000000
Expand All @@ -144,30 +148,31 @@ import sys
import CloudFlare

def main():
zone_name = sys.argv[1]
cf = CloudFlare.CloudFlare()
zone_info = cf.zones.post(data={'jump_start':False, 'name': zone_name})
zone_id = zone_info['id']

dns_records = [
{'name':'foo', 'type':'AAAA', 'content':'2001:d8b::1'},
{'name':'foo', 'type':'A', 'content':'192.168.0.1'},
{'name':'duh', 'type':'A', 'content':'10.0.0.1', 'ttl':120},
{'name':'bar', 'type':'CNAME', 'content':'foo'},
{'name':'shakespeare', 'type':'TXT', 'content':"What's in a name? That which we call a rose by any other name ..."}
]

for dns_record in dns_records:
r = cf.zones.dns_records.post(zone_id, data=dns_record)
exit(0)
zone_name = sys.argv[1]
cf = CloudFlare.CloudFlare()
zone_info = cf.zones.post(data={'jump_start':False, 'name': zone_name})
zone_id = zone_info['id']

dns_records = [
{'name':'foo', 'type':'AAAA', 'content':'2001:d8b::1'},
{'name':'foo', 'type':'A', 'content':'192.168.0.1'},
{'name':'duh', 'type':'A', 'content':'10.0.0.1', 'ttl':120},
{'name':'bar', 'type':'CNAME', 'content':'foo'},
{'name':'shakespeare', 'type':'TXT', 'content':"What's in a name? That which we call a rose by any other name ..."}
]

for dns_record in dns_records:
r = cf.zones.dns_records.post(zone_id, data=dns_record)
exit(0)

if __name__ == '__main__':
main()
main()
```

## CLI

All API calls can be called from the command line. The command will convert domain names on-the-fly into zone_identifier's.
All API calls can be called from the command line.
The command will convert domain names on-the-fly into zone_identifier's.

```bash
$ cli4 [-h|--help] [-v|--verbose] [-q|--quiet] [--get|--patch|--post|-put|--delete] [item=value ...] /command...
Expand Down Expand Up @@ -219,7 +224,8 @@ $ cli4 --delete /zones/:example.com/dns_records/:test.example.com | jq -c .
$
```

There's the ability to handle dns entries with multiple values. This produces more than one API call within the command.
There's the ability to handle dns entries with multiple values.
This produces more than one API call within the command.

```
$ cli4 /zones/:example.com/dns_records/:test.example.com | jq -c '.[]|{"id":.id,"name":.name,"type":.type,"content":.content}'
Expand Down Expand Up @@ -256,7 +262,7 @@ $ cli4 /zones/:example.com/available_plans | jq -c '.[]|{"id":.id,"name":.name}'
{"id":"1ac039f6c29b691475c3d74fe588d1ae","name":"Business Website"}
{"id":"94f3b7b768b0458b56d2cac4fe5ec0f9","name":"Enterprise Website"}
{"id":"0feeeeeeeeeeeeeeeeeeeeeeeeeeeeee","name":"Free Website"}
$
$
```

### DNSSEC CLI examples
Expand All @@ -270,21 +276,21 @@ $ cli4 --patch status=active /zones/:example.com/dnssec | jq -c '{"status":.stat
{"status":"pending"}
$

$ cli4 /zones/:example.com/dnssec
$ cli4 /zones/:example.com/dnssec
{
"algorithm": "13",
"digest": "41600621c65065b09230ebc9556ced937eb7fd86e31635d0025326ccf09a7194",
"digest_algorithm": "SHA256",
"digest_type": "2",
"ds": "example.com. 3600 IN DS 2371 13 2 41600621c65065b09230ebc9556ced937eb7fd86e31635d0025326ccf09a7194",
"flags": 257,
"key_tag": 2371,
"key_type": "ECDSAP256SHA256",
"modified_on": "2016-05-01T22:42:15.591158Z",
"public_key": "mdsswUyr3DPW132mOi8V9xESWE8jTo0dxCjjnopKl+GqJxpVXckHAeF+KkxLbxILfDLUT0rAK9iUzy1L53eKGQ==",
"algorithm": "13",
"digest": "41600621c65065b09230ebc9556ced937eb7fd86e31635d0025326ccf09a7194",
"digest_algorithm": "SHA256",
"digest_type": "2",
"ds": "example.com. 3600 IN DS 2371 13 2 41600621c65065b09230ebc9556ced937eb7fd86e31635d0025326ccf09a7194",
"flags": 257,
"key_tag": 2371,
"key_type": "ECDSAP256SHA256",
"modified_on": "2016-05-01T22:42:15.591158Z",
"public_key": "mdsswUyr3DPW132mOi8V9xESWE8jTo0dxCjjnopKl+GqJxpVXckHAeF+KkxLbxILfDLUT0rAK9iUzy1L53eKGQ==",
"status": "pending"
}
$
$
```

## Implemented API calls
Expand Down Expand Up @@ -365,12 +371,12 @@ $

Extra API calls can be added via the configuration file
```bash
$ cat ~/.cloudflare/cloudflare.cfg
$ cat ~/.cloudflare/cloudflare.cfg
[CloudFlare]
extras=
/client/v4/command
/client/v4/command/:command_identifier
/client/v4/command/:command_identifier/settings
/client/v4/command
/client/v4/command/:command_identifier
/client/v4/command/:command_identifier/settings
$
```

Expand All @@ -390,11 +396,20 @@ The following error can be caused by an out of date SSL/TLS library and/or out o

The solution can be found [here](https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning) and/or [here](http://stackoverflow.com/questions/35144550/how-to-install-cryptography-on-ubuntu).

## Python 2.x vs 3.x support

As of May/June 2016 the code is now tested againt pylint.
This was required in order to move the codebase into Python 3.x.
The motivation for this came from [Danielle Madeley (danni)](https://github.com/danni).

While the codebase has been edited to run on Python 3.x, there's not been enough Python 3.x testing performed.
If you can help in this regard; please contact the maintainers.

## Credit

This is based on work by [Felix Wong (gnowxilef)](https://github.com/gnowxilef) found [here](https://github.com/cloudflare-api/python-cloudflare-v4). It has been seriously expanded upon.
This is based on work by [Felix Wong (gnowxilef)](https://github.com/gnowxilef) found [here](https://github.com/cloudflare-api/python-cloudflare-v4).
It has been seriously expanded upon.

## Copyright

Portions copyright [Felix Wong (gnowxilef)](https://github.com/gnowxilef) 2015 and CloudFlare 2016.

51 changes: 32 additions & 19 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ Via github
$ sudo ./setup.py install
$
Or whatever variance of that you want to use.
Or whatever variance of that you want to use. There is a Makefile
included.

CloudFlare API version 4
------------------------
Expand Down Expand Up @@ -144,7 +145,7 @@ Using configuration file to store email and keys

.. code:: bash
$ cat ~/.cloudflare/cloudflare.cfg
$ cat ~/.cloudflare/cloudflare.cfg
[CloudFlare]
email = [email protected]
token = 00000000000000000000000000000000
Expand Down Expand Up @@ -290,7 +291,7 @@ A somewhat useful listing of available plans for a specific zone.
{"id":"1ac039f6c29b691475c3d74fe588d1ae","name":"Business Website"}
{"id":"94f3b7b768b0458b56d2cac4fe5ec0f9","name":"Enterprise Website"}
{"id":"0feeeeeeeeeeeeeeeeeeeeeeeeeeeeee","name":"Free Website"}
$
$
DNSSEC CLI examples
~~~~~~~~~~~~~~~~~~~
Expand All @@ -305,21 +306,21 @@ DNSSEC CLI examples
{"status":"pending"}
$
$ cli4 /zones/:example.com/dnssec
$ cli4 /zones/:example.com/dnssec
{
"algorithm": "13",
"digest": "41600621c65065b09230ebc9556ced937eb7fd86e31635d0025326ccf09a7194",
"digest_algorithm": "SHA256",
"digest_type": "2",
"ds": "example.com. 3600 IN DS 2371 13 2 41600621c65065b09230ebc9556ced937eb7fd86e31635d0025326ccf09a7194",
"flags": 257,
"key_tag": 2371,
"key_type": "ECDSAP256SHA256",
"modified_on": "2016-05-01T22:42:15.591158Z",
"public_key": "mdsswUyr3DPW132mOi8V9xESWE8jTo0dxCjjnopKl+GqJxpVXckHAeF+KkxLbxILfDLUT0rAK9iUzy1L53eKGQ==",
"algorithm": "13",
"digest": "41600621c65065b09230ebc9556ced937eb7fd86e31635d0025326ccf09a7194",
"digest_algorithm": "SHA256",
"digest_type": "2",
"ds": "example.com. 3600 IN DS 2371 13 2 41600621c65065b09230ebc9556ced937eb7fd86e31635d0025326ccf09a7194",
"flags": 257,
"key_tag": 2371,
"key_type": "ECDSAP256SHA256",
"modified_on": "2016-05-01T22:42:15.591158Z",
"public_key": "mdsswUyr3DPW132mOi8V9xESWE8jTo0dxCjjnopKl+GqJxpVXckHAeF+KkxLbxILfDLUT0rAK9iUzy1L53eKGQ==",
"status": "pending"
}
$
$
Implemented API calls
---------------------
Expand Down Expand Up @@ -473,12 +474,12 @@ Extra API calls can be added via the configuration file

.. code:: bash
$ cat ~/.cloudflare/cloudflare.cfg
$ cat ~/.cloudflare/cloudflare.cfg
[CloudFlare]
extras=
/client/v4/command
/client/v4/command/:command_identifier
/client/v4/command/:command_identifier/settings
/client/v4/command
/client/v4/command/:command_identifier
/client/v4/command/:command_identifier/settings
$
While it's easy to call anything within CloudFlare's API, it's not very
Expand All @@ -503,6 +504,18 @@ The solution can be found
and/or
`here <http://stackoverflow.com/questions/35144550/how-to-install-cryptography-on-ubuntu>`__.

Python 2.x vs 3.x support
-------------------------

As of May/June 2016 the code is now tested againt pylint. This was
required in order to move the codebase into Python 3.x. The motivation
for this came from `Danielle Madeley
(danni) <https://github.com/danni>`__.

While the codebase has been edited to run on Python 3.x, there's not
been enough Python 3.x testing performed. If you can help in this
regard; please contact the maintainers.

Credit
------

Expand Down
0 examples/example-are-zones-ipv6.py → examples/example_are_zones_ipv6.py
View file
File renamed without changes.
0 examples/example-are-zones-ipv6-simple.py → examples/example_are_zones_ipv6_simple.py
View file
File renamed without changes.
0 examples/example-certificates.py → examples/example_certificates.py
View file
File renamed without changes.
0 examples/example-create-zone-and-populate.py → examples/example_create_zone_and_populate.py
View file
File renamed without changes.
0 examples/example-dnssec-settings.py → examples/example_dnssec_settings.py
View file
File renamed without changes.
0 examples/example-ips.py → examples/example_ips.py
View file
File renamed without changes.
0 examples/example-page-rules.sh → examples/example_page_rules.sh
View file
File renamed without changes.
0 examples/example-proxied.py → examples/example_proxied.py
View file
File renamed without changes.
0 examples/example-settings.py → examples/example_settings.py
View file
File renamed without changes.
0 examples/example-update-dynamic-dns.py → examples/example_update_dynamic_dns.py
View file
File renamed without changes.
0 examples/example-user.py → examples/example_user.py
View file
File renamed without changes.
0 examples/example-zones.py → examples/example_zones.py
View file
File renamed without changes.

0 comments on commit 9e850db

Please sign in to comment.