From 39caac0808a460b84f9ae3197ecb132906323243 Mon Sep 17 00:00:00 2001 From: Ilgiz Islamgulov Date: Tue, 31 Jul 2012 05:04:55 +0600 Subject: [PATCH] update dns docstrings --- libcloud/dns/base.py | 93 +++++++++++++++++++++++-------------- libcloud/dns/drivers/dummy.py | 18 ++++++- libcloud/dns/drivers/linode.py | 29 +++++++----- libcloud/dns/drivers/rackspace.py | 10 ++-- libcloud/dns/drivers/route53.py | 22 ++++----- libcloud/dns/drivers/zerigo.py | 33 +++++++++---- 6 files changed, 132 insertions(+), 73 deletions(-) diff --git libcloud/dns/base.py libcloud/dns/base.py index d429c74..c147916 100644 --- libcloud/dns/base.py +++ libcloud/dns/base.py @@ -19,7 +19,6 @@ __all__ = [ 'DNSDriver' ] - from libcloud.common.base import ConnectionUserAndKey, BaseDriver from libcloud.dns.types import RecordType @@ -133,10 +132,11 @@ class DNSDriver(BaseDriver): name = None website = None - def __init__(self, key, secret=None, secure=True, host=None, port=None, **kwargs): + def __init__(self, key, secret=None, secure=True, host=None, port=None, + **kwargs): """ - @param key: API key or username to used (required) - @type key: C{str} + @param key: API key or username to used (required) + @type key: C{str} @param secret: Secret password to be used (required) @type secret: C{str} @@ -160,7 +160,7 @@ class DNSDriver(BaseDriver): """ Return a list of RecordType objects supported by the provider. - @return: A list of C{RecordType} instances. + @rtype: C{list} of L{RecordType} """ return list(self.RECORD_TYPE_MAP.keys()) @@ -168,7 +168,7 @@ class DNSDriver(BaseDriver): """ Return a list of zones. - @return: A list of C{Zone} instances. + @rtype: C{list} of L{Zone} """ raise NotImplementedError( 'list_zones not implemented for this driver') @@ -177,10 +177,10 @@ class DNSDriver(BaseDriver): """ Return a list of records for the provided zone. - @type zone: C{Zone} @param zone: Zone to list records for. + @type zone: L{Zone} - @return: A list of C{Record} instances. + @rtype: C{list} of L{Record} """ raise NotImplementedError( 'list_records not implemented for this driver') @@ -189,7 +189,10 @@ class DNSDriver(BaseDriver): """ Return a Zone instance. - @return: C{Zone} instance. + @param zone_id: ID of the required zone + @type zone_id: C{str} + + @rtype: L{Zone} """ raise NotImplementedError( 'get_zone not implemented for this driver') @@ -198,7 +201,13 @@ class DNSDriver(BaseDriver): """ Return a Record instance. - @return: C{Record} instance. + @param zone_id: ID of the required zone + @type zone_id: C{str} + + @param record_id: ID of the required record + @type record_id: C{str} + + @rtype: L{Record} """ raise NotImplementedError( 'get_record not implemented for this driver') @@ -207,17 +216,19 @@ class DNSDriver(BaseDriver): """ Create a new zone. - @type domain: C{string} @param domain: Zone domain name. + @type domain: C{str} - @type type: C{string} @param type: Zone type (master / slave). + @type type: C{str} - @param ttl: C{int} @param ttl: (optional) TTL for new records. + @type ttl: C{int} - @type extra: C{dict} @param extra: (optional) Extra attributes (driver specific). + @type extra: C{dict} + + @rtype: L{Zone} """ raise NotImplementedError( 'create_zone not implemented for this driver') @@ -226,20 +237,22 @@ class DNSDriver(BaseDriver): """ Update en existing zone. - @type zone: C{Zone} @param zone: Zone to update. + @type zone: L{Zone} - @type domain: C{string} @param domain: Zone domain name. + @type domain: C{str} - @type type: C{string} @param type: Zone type (master / slave). + @type type: C{str} - @param ttl: C{int} @param ttl: (optional) TTL for new records. + @type ttl: C{int} - @type extra: C{dict} @param extra: (optional) Extra attributes (driver specific). + @type extra: C{dict} + + @rtype: L{Zone} """ raise NotImplementedError( 'update_zone not implemented for this driver') @@ -248,20 +261,22 @@ class DNSDriver(BaseDriver): """ Create a new record. - @param name: C{string} - @type name: Hostname or FQDN. + @param name: Hostname or FQDN. + @type name: C{str} - @type zone: C{Zone} @param zone: Zone where the requested record is created. + @type zone: L{Zone} - @type type: C{RecordType} @param type: DNS record type (A, AAAA, ...). + @type type: L{RecordType} - @type data: C{str} @param data: Data for the record (depends on the record type). + @type data: C{str} - @type extra: C{dict} @param extra: (optional) Extra attributes (driver specific). + @type extra: C{dict} + + @rtype: L{Record} """ raise NotImplementedError( 'create_record not implemented for this driver') @@ -270,20 +285,22 @@ class DNSDriver(BaseDriver): """ Update an existing record. - @param record: C{Record} - @type record: Record to update. + @param record: Record to update. + @type record: L{Record} - @param name: C{string} - @type name: Hostname or FQDN. + @param name: Hostname or FQDN. + @type name: C{str} - @type type: C{RecordType} @param type: DNS record type (A, AAAA, ...). + @type type: L{RecordType} - @type data: C{str} @param data: Data for the record (depends on the record type). + @type data: C{str} - @type extra: C{dict} @param extra: (optional) Extra attributes (driver specific). + @type extra: C{dict} + + @rtype: L{Record} """ raise NotImplementedError( 'update_record not implemented for this driver') @@ -294,8 +311,10 @@ class DNSDriver(BaseDriver): Note: This will delete all the records belonging to this zone. - @param zone: C{Zone} - @type zone: Zone to delete. + @param zone: Zone to delete. + @type zone: L{Zone} + + @rtype: C{bool} """ raise NotImplementedError( 'delete_zone not implemented for this driver') @@ -304,8 +323,10 @@ class DNSDriver(BaseDriver): """ Delete a record. - @param record: C{Record} - @type record: Record to delete. + @param record: Record to delete. + @type record: L{Record} + + @rtype: C{bool} """ raise NotImplementedError( 'delete_record not implemented for this driver') diff --git libcloud/dns/drivers/dummy.py libcloud/dns/drivers/dummy.py index 8d19aa8..fb26166 100644 --- libcloud/dns/drivers/dummy.py +++ libcloud/dns/drivers/dummy.py @@ -50,6 +50,8 @@ class DummyDNSDriver(DNSDriver): >>> driver = DummyDNSDriver('key', 'secret') >>> driver.list_record_types() [0] + + @inherits: L{DNSDriver.list_record_types} """ return [RecordType.A] @@ -58,6 +60,8 @@ class DummyDNSDriver(DNSDriver): >>> driver = DummyDNSDriver('key', 'secret') >>> driver.list_zones() [] + + @inherits: L{DNSDriver.list_zones} """ return [zone['zone'] for zone in list(self._zones.values())] @@ -72,6 +76,8 @@ class DummyDNSDriver(DNSDriver): ... #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): ZoneDoesNotExistError: + + @inherits: L{DNSDriver.get_zone} """ if zone_id not in self._zones: @@ -87,6 +93,8 @@ class DummyDNSDriver(DNSDriver): ... #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): ZoneDoesNotExistError: + + @inherits: L{DNSDriver.get_record} """ self.get_zone(zone_id=zone_id) @@ -110,6 +118,8 @@ class DummyDNSDriver(DNSDriver): ... #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): ZoneAlreadyExistsError: + + @inherits: L{DNSDriver.create_zone} """ id = 'id-%s' % (domain) @@ -120,7 +130,7 @@ class DummyDNSDriver(DNSDriver): zone = Zone(id=id, domain=domain, type=type, ttl=ttl, extra={}, driver=self) self._zones[id] = {'zone': zone, - 'records': {}} + 'records': {}} return zone def create_record(self, name, zone, type, data, extra=None): @@ -137,6 +147,8 @@ class DummyDNSDriver(DNSDriver): ... #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): RecordAlreadyExistsError: + + @inherits: L{DNSDriver.create_record} """ id = 'id-%s' % (name) @@ -161,6 +173,8 @@ class DummyDNSDriver(DNSDriver): >>> driver.delete_zone(zone) #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): ZoneDoesNotExistError: + + @inherits: L{DNSDriver.delete_zone} """ self.get_zone(zone_id=zone.id) @@ -179,6 +193,8 @@ class DummyDNSDriver(DNSDriver): >>> driver.delete_record(record) #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): RecordDoesNotExistError: + + @inherits: L{DNSDriver.delete_record} """ self.get_record(zone_id=record.zone.id, record_id=record.id) diff --git libcloud/dns/drivers/linode.py libcloud/dns/drivers/linode.py index 1514d3d..73c8ff9 100644 --- libcloud/dns/drivers/linode.py +++ libcloud/dns/drivers/linode.py @@ -17,7 +17,6 @@ __all__ = [ 'LinodeDNSDriver' ] - from libcloud.utils.misc import merge_valid_keys, get_new_obj from libcloud.common.linode import (API_ROOT, LinodeException, LinodeConnection, LinodeResponse) @@ -41,13 +40,13 @@ class LinodeDNSResponse(LinodeResponse): if context['resource'] == 'zone': result = ZoneDoesNotExistError(value='', - driver=self.connection.driver, - zone_id=context['id']) + driver=self.connection.driver, + zone_id=context['id']) elif context['resource'] == 'record': result = RecordDoesNotExistError(value='', - driver=self.connection.driver, - record_id=context['id']) + driver=self.connection.driver, + record_id=context['id']) return result @@ -99,7 +98,7 @@ class LinodeDNSDriver(DNSDriver): def get_record(self, zone_id, record_id): zone = self.get_zone(zone_id=zone_id) params = {'api_action': 'domain.resource.list', 'DomainID': zone_id, - 'ResourceID': record_id} + 'ResourceID': record_id} data = self.connection.request(API_ROOT, params=params).objects[0] records = self._to_records(items=data, zone=zone) @@ -114,6 +113,8 @@ class LinodeDNSDriver(DNSDriver): Create a new zone. API docs: http://www.linode.com/api/dns/domain.create + + @inherits: C{DNSDriver.create_zone} """ params = {'api_action': 'domain.create', 'Type': type, 'Domain': domain} @@ -134,6 +135,8 @@ class LinodeDNSDriver(DNSDriver): Update an existing zone. API docs: http://www.linode.com/api/dns/domain.update + + @inherits: C{DNSDriver.update_zone} """ params = {'api_action': 'domain.update', 'DomainID': zone.id} @@ -151,9 +154,9 @@ class LinodeDNSDriver(DNSDriver): extra=extra) self.connection.request(API_ROOT, params=params).objects[0] updated_zone = get_new_obj(obj=zone, klass=Zone, - attributes={'domain': domain, - 'type': type, 'ttl': ttl, - 'extra': merged}) + attributes={'domain': domain, + 'type': type, 'ttl': ttl, + 'extra': merged}) return updated_zone def create_record(self, name, zone, type, data, extra=None): @@ -161,6 +164,8 @@ class LinodeDNSDriver(DNSDriver): Create a new record. API docs: http://www.linode.com/api/dns/domain.resource.create + + @inherits: C{DNSDriver.create_record} """ params = {'api_action': 'domain.resource.create', 'DomainID': zone.id, 'Name': name, 'Target': data, @@ -180,6 +185,8 @@ class LinodeDNSDriver(DNSDriver): Update an existing record. API docs: http://www.linode.com/api/dns/domain.resource.update + + @inherits: C{DNSDriver.update_record} """ params = {'api_action': 'domain.resource.update', 'ResourceID': record.id, 'DomainID': record.zone.id} @@ -239,7 +246,7 @@ class LinodeDNSDriver(DNSDriver): Build an Zone object from the item dictionary. """ extra = {'SOA_Email': item['SOA_EMAIL'], 'status': item['STATUS'], - 'description': item['DESCRIPTION']} + 'description': item['DESCRIPTION']} zone = Zone(id=item['DOMAINID'], domain=item['DOMAIN'], type=item['TYPE'], ttl=item['TTL_SEC'], driver=self, extra=extra) @@ -261,7 +268,7 @@ class LinodeDNSDriver(DNSDriver): Build a Record object from the item dictionary. """ extra = {'protocol': item['PROTOCOL'], 'ttl_sec': item['TTL_SEC'], - 'port': item['PORT'], 'weight': item['WEIGHT']} + 'port': item['PORT'], 'weight': item['WEIGHT']} type = self._string_to_record_type(item['TYPE']) record = Record(id=item['RESOURCEID'], name=item['NAME'], type=type, data=item['TARGET'], zone=zone, driver=self, diff --git libcloud/dns/drivers/rackspace.py libcloud/dns/drivers/rackspace.py index beb7ea2..5bbba56 100644 --- libcloud/dns/drivers/rackspace.py +++ libcloud/dns/drivers/rackspace.py @@ -80,7 +80,7 @@ class RackspaceDNSConnection(OpenStack_1_1_Connection, PollingConnection): def get_poll_request_kwargs(self, response, context, request_kwargs): job_id = response.object['jobId'] kwargs = {'action': '/status/%s' % (job_id), - 'params': {'showDetails': True}} + 'params': {'showDetails': True}} return kwargs def has_completed(self, response): @@ -104,13 +104,13 @@ class RackspaceDNSConnection(OpenStack_1_1_Connection, PollingConnection): return self._construct_dns_endpoint_from_servers_endpoint(ep) elif "2.0" in self._auth_version: ep = self.service_catalog.get_endpoint(name="cloudServers", - service_type="compute", - region=None) + service_type="compute", + region=None) return self._construct_dns_endpoint_from_servers_endpoint(ep) else: - raise LibcloudError("Auth version %s not supported" % \ - self._auth_version) + raise LibcloudError("Auth version %s not supported" % + (self._auth_version)) def _construct_dns_endpoint_from_servers_endpoint(self, ep): if 'publicURL' in ep: diff --git libcloud/dns/drivers/route53.py libcloud/dns/drivers/route53.py index fdaefe7..275735f 100644 --- libcloud/dns/drivers/route53.py +++ libcloud/dns/drivers/route53.py @@ -52,7 +52,7 @@ class Route53Error(LibcloudError): def __repr__(self): return('' % - (self.code, len(self.errors))) + (self.code, len(self.errors))) class Route53DNSResponse(AWSBaseResponse): @@ -79,7 +79,7 @@ class Route53DNSResponse(AWSBaseResponse): messages.append(message['Message']) raise Route53Error('InvalidChangeBatch message(s): %s ', - messages) + messages) class Route53Connection(ConnectionUserAndKey): @@ -164,7 +164,7 @@ class Route53DNSDriver(DNSDriver): def _to_zone(self, elem): name = findtext(element=elem, xpath='Name', namespace=NAMESPACE) id = findtext(element=elem, xpath='Id', - namespace=NAMESPACE).replace('/hostedzone/', '') + namespace=NAMESPACE).replace('/hostedzone/', '') comment = findtext(element=elem, xpath='Config/Comment', namespace=NAMESPACE) resource_record_count = int(findtext(element=elem, @@ -172,7 +172,7 @@ class Route53DNSDriver(DNSDriver): namespace=NAMESPACE)) extra = {'Comment': comment, 'ResourceRecordSetCount': - resource_record_count} + resource_record_count} zone = Zone(id=id, domain=name, type='master', ttl=0, driver=self, extra=extra) @@ -180,24 +180,24 @@ class Route53DNSDriver(DNSDriver): def _to_records(self, data, zone): records = [] - for elem in \ - data.findall(fixxpath(xpath='ResourceRecordSets/ResourceRecordSet', - namespace=NAMESPACE)): + for elem in data.findall( + fixxpath(xpath='ResourceRecordSets/ResourceRecordSet', + namespace=NAMESPACE)): records.append(self._to_record(elem, zone)) return records def _to_record(self, elem, zone): name = findtext(element=elem, xpath='Name', - namespace=NAMESPACE) + namespace=NAMESPACE) type = self._string_to_record_type(findtext(element=elem, xpath='Type', - namespace=NAMESPACE)) + namespace=NAMESPACE)) ttl = findtext(element=elem, xpath='TTL', namespace=NAMESPACE) # TODO: Support records with multiple values value_elem = elem.findall( - fixxpath(xpath='ResourceRecords/ResourceRecord', - namespace=NAMESPACE))[0] + fixxpath(xpath='ResourceRecords/ResourceRecord', + namespace=NAMESPACE))[0] data = findtext(element=(value_elem), xpath='Value', namespace=NAMESPACE) diff --git libcloud/dns/drivers/zerigo.py libcloud/dns/drivers/zerigo.py index 907c8cf..6ab9909 100644 --- libcloud/dns/drivers/zerigo.py +++ libcloud/dns/drivers/zerigo.py @@ -55,9 +55,8 @@ class ZerigoError(LibcloudError): return 'Errors: %s' % (', '.join(self.errors)) def __repr__(self): - return ('' % - (self.code, - len(self.errors))) + return ('' % ( + self.code, len(self.errors))) class ZerigoDNSResponse(XmlResponse): @@ -173,6 +172,8 @@ class ZerigoDNSDriver(DNSDriver): Provider API docs: https://www.zerigo.com/docs/apis/dns/1.1/zones/create + + @inherits: L{DNSDriver.create_zone} """ path = API_ROOT + 'zones.xml' zone_elem = self._to_zone_elem(domain=domain, type=type, ttl=ttl, @@ -189,6 +190,8 @@ class ZerigoDNSDriver(DNSDriver): Provider API docs: https://www.zerigo.com/docs/apis/dns/1.1/zones/update + + @inherits: L{DNSDriver.update_zone} """ if domain: raise LibcloudError('Domain cannot be changed', driver=self) @@ -197,8 +200,8 @@ class ZerigoDNSDriver(DNSDriver): zone_elem = self._to_zone_elem(domain=domain, type=type, ttl=ttl, extra=extra) response = self.connection.request(action=path, - data=ET.tostring(zone_elem), - method='PUT') + data=ET.tostring(zone_elem), + method='PUT') assert response.status == httplib.OK merged = merge_valid_keys(params=copy.deepcopy(zone.extra), @@ -216,6 +219,8 @@ class ZerigoDNSDriver(DNSDriver): Provider API docs: https://www.zerigo.com/docs/apis/dns/1.1/hosts/create + + @inherits: L{DNSDriver.create_record} """ path = API_ROOT + 'zones/%s/hosts.xml' % (zone.id) record_elem = self._to_record_elem(name=name, type=type, data=data, @@ -261,6 +266,11 @@ class ZerigoDNSDriver(DNSDriver): def ex_get_zone_by_domain(self, domain): """ Retrieve a zone object by the domain name. + + @param domain: The domain which should be used + @type domain: C{str} + + @rtype: L{Zone} """ path = API_ROOT + 'zones/%s.xml' % (domain) self.connection.set_context({'resource': 'zone', 'id': domain}) @@ -271,6 +281,11 @@ class ZerigoDNSDriver(DNSDriver): def ex_force_slave_axfr(self, zone): """ Force a zone transfer. + + @param zone: Zone which should be used. + @type zone: L{Zone} + + @rtype: L{Zone} """ path = API_ROOT + 'zones/%s/force_slave_axfr.xml' % (zone.id) self.connection.set_context({'resource': 'zone', 'id': zone.id}) @@ -308,7 +323,7 @@ class ZerigoDNSDriver(DNSDriver): ns_type_elem.text = 'pri' slave_nameservers_elem = ET.SubElement(zone_elem, - 'slave-nameservers') + 'slave-nameservers') slave_nameservers_elem.text = extra['slave-nameservers'] if ttl: @@ -383,9 +398,9 @@ class ZerigoDNSDriver(DNSDriver): tags = tags.split(' ') if tags else [] extra = {'hostmaster': hostmaster, 'custom-ns': custom_ns, - 'custom-nameservers': custom_nameservers, 'notes': notes, - 'nx-ttl': nx_ttl, 'slave-nameservers': slave_nameservers, - 'tags': tags} + 'custom-nameservers': custom_nameservers, 'notes': notes, + 'nx-ttl': nx_ttl, 'slave-nameservers': slave_nameservers, + 'tags': tags} zone = Zone(id=str(id), domain=domain, type=type, ttl=int(ttl), driver=self, extra=extra) return zone -- 1.7.9.5