diff --git a/CloudFlare/__init__.py b/CloudFlare/__init__.py index 113265a..29483f8 100644 --- a/CloudFlare/__init__.py +++ b/CloudFlare/__init__.py @@ -2,4 +2,4 @@ from cloudflare import CloudFlare -__version__ = '1.2.3' +__version__ = '1.2.4' diff --git a/README.md b/README.md index ec50c0f..27b9e96 100644 --- a/README.md +++ b/README.md @@ -68,8 +68,8 @@ if __name__ == '__main__': A more complex example follows. ```python -import sys import CloudFlare +import CloudFlare.exceptions def main(): zone_name = 'example.com' @@ -79,11 +79,14 @@ def main(): # 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: + except CloudFlare.exceptions.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)) + if len(zones) == 0: + exit('No zones found') + # extract the zone_id which is needed to process that zone zone = zones[0] zone_id = zone['id'] @@ -91,7 +94,7 @@ def main(): # request the DNS records from that zone try: dns_records = cf.zones.dns_records.get(zone_id) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones/dns_records.get %d %s - api call failed' % (e, e)) # print the results - first the zone name @@ -171,7 +174,9 @@ You can leave *extras* in the configuration with a blank value (or omit the opti ## Exceptions and return values -The response is build from the JSON in the API call. +### Response data + +The response is build from the JSON in the API call. It contains the **results** values; but does not contain the paging values. You can return all the paging values by calling the class with raw=True. Here's an example without paging. @@ -235,6 +240,26 @@ This produces. A full example of paging is provided below. + +### Exceptions + +The library will raise **CloudFlareAPIError** when the API call fails. +The exception returns both an integer and textual message in one value. + +```python +import CloudFlare +import CloudFlare.exceptions + + ... + try + r = ... + except CloudFlare.exceptions.CloudFlareAPIError as e: + exit('api error: %d %s' % (e, e)) + ... +``` + +The other raised response is **CloudFlareInternalError** which can happen when calling an invalid method. + ## Included example code The [examples](https://github.com/cloudflare/python-cloudflare/tree/master/examples) folder contains many examples in both simple and verbose formats. diff --git a/README.rst b/README.rst index 842cc45..2d94510 100644 --- a/README.rst +++ b/README.rst @@ -84,8 +84,8 @@ A more complex example follows. .. code:: python - import sys import CloudFlare + import CloudFlare.exceptions def main(): zone_name = 'example.com' @@ -95,11 +95,14 @@ A more complex example follows. # 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: + except CloudFlare.exceptions.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)) + if len(zones) == 0: + exit('No zones found') + # extract the zone_id which is needed to process that zone zone = zones[0] zone_id = zone['id'] @@ -107,7 +110,7 @@ A more complex example follows. # request the DNS records from that zone try: dns_records = cf.zones.dns_records.get(zone_id) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones/dns_records.get %d %s - api call failed' % (e, e)) # print the results - first the zone name @@ -199,6 +202,9 @@ value (or omit the option variable fully). Exceptions and return values ---------------------------- +Response data +~~~~~~~~~~~~~ + The response is build from the JSON in the API call. It contains the **results** values; but does not contain the paging values. @@ -265,6 +271,27 @@ This produces. A full example of paging is provided below. +Exceptions +~~~~~~~~~~ + +The library will raise **CloudFlareAPIError** when the API call fails. +The exception returns both an integer and textual message in one value. + +.. code:: python + + import CloudFlare + import CloudFlare.exceptions + + ... + try + r = ... + except CloudFlare.exceptions.CloudFlareAPIError as e: + exit('api error: %d %s' % (e, e)) + ... + +The other raised response is **CloudFlareInternalError** which can +happen when calling an invalid method. + Included example code --------------------- diff --git a/examples/example_are_zones_ipv6.py b/examples/example_are_zones_ipv6.py index 8ee1043..434f870 100755 --- a/examples/example_are_zones_ipv6.py +++ b/examples/example_are_zones_ipv6.py @@ -6,6 +6,7 @@ sys.path.insert(0, os.path.abspath('..')) import CloudFlare +import CloudFlare.exceptions def main(): """Cloudflare API code - example""" @@ -31,7 +32,7 @@ def main(): # grab the zone identifier try: zones = cf.zones.get(params=params) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.get %d %s - api call failed' % (e, e)) except Exception as e: exit('/zones - %s - api call failed' % (e)) @@ -41,7 +42,7 @@ def main(): zone_id = zone['id'] try: ipv6 = cf.zones.settings.ipv6.get(zone_id) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.settings.ipv6.get %d %s - api call failed' % (e, e)) ipv6_value = ipv6['value'] @@ -49,7 +50,7 @@ def main(): print zone_id, ipv6_value, zone_name, '(now updating... off -> on)' try: ipv6 = cf.zones.settings.ipv6.patch(zone_id, data={'value':'on'}) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.settings.ipv6.patch %d %s - api call failed' % (e, e)) ipv6_value = ipv6['value'] if ipv6_value == 'on': diff --git a/examples/example_certificates.py b/examples/example_certificates.py index f60c817..ac45dd9 100755 --- a/examples/example_certificates.py +++ b/examples/example_certificates.py @@ -7,6 +7,7 @@ sys.path.insert(0, os.path.abspath('..')) import CloudFlare +import CloudFlare.exceptions def main(): """Cloudflare API code - example""" @@ -23,7 +24,7 @@ def main(): # grab the zone identifier try: zones = cf.zones.get(params=params) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones %d %s - api call failed' % (e, e)) except Exception as e: exit('/zones - %s - api call failed' % (e)) @@ -34,7 +35,7 @@ def main(): zone_id = zone['id'] try: certificates = cf.zones.ssl.certificate_packs.get(zone_id) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.ssl.certificate_packs %d %s - api call failed' % (e, e)) for certificate in certificates: diff --git a/examples/example_create_zone_and_populate.py b/examples/example_create_zone_and_populate.py index 48346f9..b2c1a26 100755 --- a/examples/example_create_zone_and_populate.py +++ b/examples/example_create_zone_and_populate.py @@ -6,6 +6,7 @@ sys.path.insert(0, os.path.abspath('..')) import CloudFlare +import CloudFlare.exceptions def main(): """Cloudflare API code - example""" @@ -23,7 +24,7 @@ def main(): print 'Create zone %s ...' % (zone_name) try: zone_info = cf.zones.post(data={'jump_start':False, 'name': zone_name}) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.post %s - %d %s' % (zone_name, e, e)) except Exception as e: exit('/zones.post %s - %s' % (zone_name, e)) @@ -58,7 +59,7 @@ def main(): # Create DNS record try: r = cf.zones.dns_records.post(zone_id, data=dns_record) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.dns_records.post %s %s - %d %s' % (zone_name, dns_record['name'], e, e)) # Print respose info - they should be the same dns_record = r @@ -86,7 +87,7 @@ def main(): try: dns_record = cf.zones.dns_records.put(zone_id, dns_record_id, data=new_dns_record) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones/dns_records.put %d %s - api call failed' % (e, e)) print '' @@ -95,7 +96,7 @@ def main(): print 'Read back DNS records ...' try: dns_records = cf.zones.dns_records.get(zone_id) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.dns_records.get %s - %d %s' % (zone_name, e, e)) for dns_record in sorted(dns_records, key=lambda v: v['name']): diff --git a/examples/example_dnssec_settings.py b/examples/example_dnssec_settings.py index cf3cc86..5b189c1 100755 --- a/examples/example_dnssec_settings.py +++ b/examples/example_dnssec_settings.py @@ -6,6 +6,7 @@ sys.path.insert(0, os.path.abspath('..')) import CloudFlare +import CloudFlare.exceptions def main(): """Cloudflare API code - example""" @@ -22,7 +23,7 @@ def main(): # grab the zone identifier try: zones = cf.zones.get(params=params) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.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)) @@ -34,7 +35,7 @@ def main(): # grab the DNSSEC settings try: settings = cf.zones.dnssec.get(zone_id) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.dnssec.get %d %s - api call failed' % (e, e)) print zone_id, zone_name diff --git a/examples/example_ips.py b/examples/example_ips.py index 6f8bd6b..f950dd1 100755 --- a/examples/example_ips.py +++ b/examples/example_ips.py @@ -6,6 +6,7 @@ sys.path.insert(0, os.path.abspath('..')) import CloudFlare +import CloudFlare.exceptions def main(): """Cloudflare API code - example""" @@ -13,7 +14,7 @@ def main(): cf = CloudFlare.CloudFlare() try: ips = cf.ips.get() - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/ips - %d %s' % (e, e)) except Exception as e: exit('/ips - %s - api call connection failed' % (e)) diff --git a/examples/example_proxied.py b/examples/example_proxied.py index e88d431..7089fe6 100755 --- a/examples/example_proxied.py +++ b/examples/example_proxied.py @@ -6,6 +6,7 @@ sys.path.insert(0, os.path.abspath('..')) import CloudFlare +import CloudFlare.exceptions def main(): """Change the proxied value on a FQDN""" @@ -30,7 +31,7 @@ def main(): try: params = {'name':zone_name, 'per_page':1} zones = cf.zones.get(params=params) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.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)) @@ -49,7 +50,7 @@ def main(): try: params = {'name': dns_name} dns_records = cf.zones.dns_records.get(zone_id, params=params) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones/dns_records.get %d %s - api call failed' % (e, e)) if len(dns_records) == 0: @@ -86,7 +87,7 @@ def main(): try: dns_record = cf.zones.dns_records.put(zone_id, dns_record_id, data=new_dns_record) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones/dns_records.put %d %s - api call failed' % (e, e)) r_zone_id = dns_record['zone_id'] diff --git a/examples/example_settings.py b/examples/example_settings.py index 4842133..925bc87 100755 --- a/examples/example_settings.py +++ b/examples/example_settings.py @@ -6,6 +6,7 @@ sys.path.insert(0, os.path.abspath('..')) import CloudFlare +import CloudFlare.exceptions def main(): """Cloudflare API code - example""" @@ -22,7 +23,7 @@ def main(): # grab the zone identifier try: zones = cf.zones.get(params=params) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.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)) @@ -33,7 +34,7 @@ def main(): zone_id = zone['id'] try: settings = cf.zones.settings.get(zone_id) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.settings.get %d %s - api call failed' % (e, e)) print zone_id, zone_name diff --git a/examples/example_update_dynamic_dns.py b/examples/example_update_dynamic_dns.py index 4058836..4f7be5f 100755 --- a/examples/example_update_dynamic_dns.py +++ b/examples/example_update_dynamic_dns.py @@ -9,6 +9,7 @@ sys.path.insert(0, os.path.abspath('..')) import CloudFlare +import CloudFlare.exceptions def my_ip_address(): """Cloudflare API code - example""" @@ -38,7 +39,7 @@ def do_dns_update(cf, zone_name, zone_id, dns_name, ip_address, ip_address_type) try: params = {'name':dns_name, 'match':'all', 'type':ip_address_type} dns_records = cf.zones.dns_records.get(zone_id, params=params) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones/dns_records %s - %d %s - api call failed' % (dns_name, e, e)) updated = False @@ -73,7 +74,7 @@ def do_dns_update(cf, zone_name, zone_id, dns_name, ip_address, ip_address_type) } try: dns_record = cf.zones.dns_records.put(zone_id, dns_record_id, data=dns_record) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.dns_records.put %s - %d %s - api call failed' % (dns_name, e, e)) print 'UPDATED: %s %s -> %s' % (dns_name, old_ip_address, ip_address) updated = True @@ -89,7 +90,7 @@ def do_dns_update(cf, zone_name, zone_id, dns_name, ip_address, ip_address_type) } try: dns_record = cf.zones.dns_records.post(zone_id, data=dns_record) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones.dns_records.post %s - %d %s - api call failed' % (dns_name, e, e)) print 'CREATED: %s %s' % (dns_name, ip_address) @@ -113,7 +114,7 @@ def main(): try: params = {'name':zone_name} zones = cf.zones.get(params=params) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones %d %s - api call failed' % (e, e)) except Exception as e: exit('/zones.get - %s - api call failed' % (e)) diff --git a/examples/example_user.py b/examples/example_user.py index 39d23fe..ae462b2 100755 --- a/examples/example_user.py +++ b/examples/example_user.py @@ -7,6 +7,7 @@ sys.path.insert(0, os.path.abspath('..')) import CloudFlare +import CloudFlare.exceptions def main(): """Cloudflare API code - example""" @@ -17,7 +18,7 @@ def main(): # grab the user info try: user = cf.user.get() - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/user.get %d %s - api call failed' % (e, e)) except Exception as e: exit('/user.get - %s - api call failed' % (e)) @@ -45,7 +46,7 @@ def main(): # grab the user organizations info try: organizations = cf.user.organizations.get() - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/user.organizations.get %d %s - api call failed' % (e, e)) if len(organizations) == 0: print '\tNo organization' @@ -60,7 +61,7 @@ def main(): # grab the user invites info try: invites = cf.user.invites.get() - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/user.invites.get %d %s - api call failed' % (e, e)) if len(invites) == 0: print '\tNo user invites' @@ -89,7 +90,7 @@ def main(): # grab the user billing profile info try: profile = cf.user.billing.profile.get() - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/user.billing.profile.get %d %s - api call failed' % (e, e)) profile_id = profile['id'] profile_first = profile['first_name'] @@ -139,7 +140,7 @@ def main(): # grab the user billing history info try: history = cf.user.billing.history.get() - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/user.billing.history.get %d %s - api call failed' % (e, e)) if len(history) == 0: print '\tNo billing history' diff --git a/examples/example_zones.py b/examples/example_zones.py index 7452fb7..8913724 100755 --- a/examples/example_zones.py +++ b/examples/example_zones.py @@ -7,6 +7,7 @@ sys.path.insert(0, os.path.abspath('..')) import CloudFlare +import CloudFlare.exceptions def main(): """Cloudflare API code - example""" @@ -23,7 +24,7 @@ def main(): # grab the zone identifier try: zones = cf.zones.get(params=params) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones %d %s - api call failed' % (e, e)) except Exception as e: exit('/zones.get - %s - api call failed' % (e)) @@ -40,7 +41,7 @@ def main(): try: dns_records = cf.zones.dns_records.get(zone_id) - except CloudFlare.CloudFlareAPIError as e: + except CloudFlare.exceptions.CloudFlareAPIError as e: exit('/zones/dns_records %d %s - api call failed' % (e, e)) print zone_id, zone_name, zone_owner, zone_plan