cloudns Package¶

`cloudns` Package¶

cloudns API python client.

The cloudns API is documented at http://wiki.dev.game.yy.com/moin/DNS

This python client is based on that API.

The major version of this client tries to match the the API version. Thus 1.1.* (or later) supports API v1.1.

`base` Module¶

defines exception types and constants

exception cloudns.base.CloudnsBadUsage¶: Bases: cloudns.base.CloudnsError

exception cloudns.base.CloudnsError¶: Bases: exceptions.Exception

exception cloudns.base.CloudnsRuntimeError¶: Bases: cloudns.base.CloudnsError, exceptions.RuntimeError

exception cloudns.base.CloudnsServerError¶

Bases: cloudns.base.CloudnsRuntimeError

an error occurred on cloudns server, not your fault.

exception cloudns.base.CloudnsValidationError¶: Bases: cloudns.base.CloudnsError

exception cloudns.base.DuplicateRecord¶

Bases: cloudns.base.CloudnsRuntimeError

raised when you want to create a duplicate record.

two records are dup if zone, name, content, isp are all the same.

exception cloudns.base.RecordNotFound¶: Bases: cloudns.base.CloudnsRuntimeError

exception cloudns.base.RecordNotReady¶

Bases: cloudns.base.CloudnsRuntimeError

raised when you delete a record that is in PENDING_ACTIVE status.

`record` Module¶

defines the Record class

class cloudns.record.Record(**kwargs)¶

Bases: object

a record is a simple object with these attribute:

It represents a record in cloudns system.

attr	description
rid	record id
type	record type
name	DNS label
content	DNS value
isp	tel or uni for China Telecom and China Unicom
ctime	last modification timestamp
z	zone name
ttl	DNS TTL
prio	MX priority, default is 0
status	this is returned from server. 0 means PENDING_ACTIVE, 1 means ACTIVE, 2 means PENDING_REMOVAL.

RESERVED_ATTRIBUTES = ('rid', 'name', 'type', 'content', 'isp', 'ctime', 'z', 'ttl', 'prio', 'status')¶

as_dict()¶

update(**kwargs)¶

return a new Record with given values replaced.

allowed keys:: z, name, content, isp, type, ttl

rid is not allowed here, because it is used to locate which record to update.

`user` Module¶

defines the User class

class cloudns.user.User(passport=None, token=None, api=None)¶

Bases: object

a User in cloudns admin system.

A User can manage any zone or record it has permission with.

A User is identified by his/her passport and is authenticated by a token.

create_record(zone, name, content, isp, type='A', ttl=300)¶

create a new record.

Note

Create duplicate record will result in DuplicateRecord raised.

Args:: zone: zone name name: the host name (a label) content: the value isp: ‘tel’ for China Telecom, ‘uni’ for China Unicom type: record type, could be ‘A’, ‘cname’ etc ttl: time to live, cache/expiration duration in seconds

create_records(zone, records)¶

add a list of records to given zone.

records example:

[{"type": "A",
  "name": "test1",
  "content": "1.2.3.4",
  "isp": "tel",
  "ttl": 300},
 {"type": "A",
  "name": "test1",
  "content": "1.2.3.4",
  "isp": "uni",
  "ttl": 300}]

Args:

records: a python object or a json string. In either case, it: should be a list of objects with these keys: type, name, content, isp, ttl.

create_zone(zone)¶: create a zone.

delete_record_by_id(zone, rid, auto_retry=False)¶

delete record by id.

if auto_retry is True, continue retry until delete is successful.

if given rid does not exist, py:class:cloudns.RecordNotFound will be raised.

delete_records(rids)¶

delete records matching given rids.

This differs from delete_record because it sends a single request to remote server.

Delete a record that is in PENDING_ACTIVE status will raise RecordNotReady exception. This is how the cloudns API works.

Args:: rids: an iterable of record ids or comma seperated ids.

delete_records_by_name(zone, name, auto_retry=False)¶

delete all records that match exactly the given name in given zone.

If auto_retry is True, continue retry until delete is successful.

If given name does not match any record, py:class:cloudns.RecordNotFound will be raised.

delete_zone(zone)¶: delete a zone.

get_all_records(zone, offset=0, limit=20)¶

get some/all records under this zone.

offset and limit has the same meaning as in MySQL’s select statement’s limit clause. They are used to limit result to a subset.

If you don’t pass in offset and limit, default behavior is fetch first 20 records.

Args:: offset: return records from this index. index is 0-based. limit: return this many records. set to -1 to get all records.
Return:: json response from server.

get_all_zones()¶: return all zones current user has permission.

get_record_by_id(zone, rid)¶: return one Record for given rid or raise RecordNotFound.

get_record_count(zone)¶: return how many records is in given zone.

Note

you can not rely on this. Because user could have added or deleted some records after you call this method.

get_records_by_name(zone, name)¶: return a list of Records that exactly match given name.

get_zone(zone)¶: return zone information for given zone.

get_zones(zones)¶

return zone information for given zones.

Args:: zones: an iterable of zones, or comma separated zones as a string.

search_record(zone, keyword)¶

return records that is in given zone and matches given keyword.

You can use * in keyword to match anything. You can use up to two * in keyword. consecutive * is not allowed.

Return:: a list of Records.

update_record(record, auto_retry=False)¶

update record by record.rid.

To update a record, first fetch a record with get_records_by_name() or get_record_by_id(), then call Record.update(), finally User.update_record() or Zone.update_record().

Here is an example:

>>> old_record = zone.get_record_by_id(rid)
>>> new_record = old_record.update(content="1.2.3.4")
>>> zone.update_record(new_record)

Args:: record: update old record with record.rid to match this record.

update_record_raw(rid, zone, name, content, isp, type, ttl, auto_retry=False)¶

update record with given rid.

You should usually use update_record() instead of this method.

zone(zone)¶

return a Zone object under this User.

Create a zone object and call methods on it so that you don’t have to pass the zone parameter all the time.

cloudns.user.join_by_comma_maybe(obj)¶

join an iterable maybe.

if obj is a string, do nothing. if obj is an iterable, join it with u’,’.

`zone` Module¶

defines the Zone class.

class cloudns.zone.Zone(user, zone_name)¶

Bases: object

a Zone can manage records in the zone easier than a User.

a Zone has a zone name (self.zone) and a binded user (self.user).

bulk create/delete records are not defined here, if you wish to use them, please use User.create_records() and User.delete_records().

create_record(name, content, isp, type='A', ttl=300)¶

create a new record.

Note

Create duplicate record will result in DuplicateRecord raised.

Args:: name: the host name (a label) content: the value isp: ‘tel’ for China Telecom, ‘uni’ for China Unicom type: record type, could be ‘A’, ‘cname’ etc ttl: time to live, cache/expiration duration in seconds

delete_record_by_id(rid, auto_retry=False)¶

delete record by id.

if auto_retry is True, continue retry until delete is successful.

if given rid does not exist, cloudns.RecordNotFound will be raised.

delete_records_by_name(name, auto_retry=False)¶

delete all records that match exactly the given name in this zone.

If auto_retry is True, continue retry until delete is successful.

If given name does not match any record, cloudns.RecordNotFound will be raised.

get_all_records(offset=0, limit=20)¶

get all records under this zone.

offset and limit has the same meaning as in MySQL’s select statement’s limit clause. They are used to limit result to a subset.

Args:: offset: return records from this index. index is 0-based. limit: return this many records. set to -1 to get all records.
Return:: json response from server.

get_record_by_id(rid)¶

return one Record for given rid.

raise RecordNotFound if record not found.

get_record_count()¶: return how many records in this zone.

Note

you can not rely on this. Because user could have added or deleted some records after you call this method.

get_records_by_name(name)¶: return a list of Records that exactly match given name.

search_record(keyword)¶

return records that is in this zone and matches given keyword.

You can use * in keyword to match anything. You can use up to two * in keyword. consecutive * is not allowed.

update_record(record, auto_retry=False)¶

update record by record.rid.

Args:: record: update old record with record.rid to match this record.

cloudns Package¶

cloudns Package¶

base Module¶

record Module¶

user Module¶

zone Module¶

`cloudns` Package¶

`base` Module¶

`record` Module¶

`user` Module¶

`zone` Module¶