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.CloudnsAuthenticationFailure¶: Bases: cloudns.base.CloudnsRuntimeError

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.

class cloudns.base.ErrorNumbers¶

Bases: object

Error Numbers as defined in upstream api.

API_IS_NOT_SUPPORTED = 1¶

AUTHENTICATE_FAILED = 3¶

DUPLICATE_USER = 7¶

DUPLICATE_ZONE = 8¶

HTTP_METHOD_IS_NOT_SUPPORTED = 2¶

NOERROR = 0¶

PARA_IS_INVALID = 5¶

PARA_IS_REQUIRED = 4¶

PERMISSION_DENIED = 6¶

PROCESS_FAILED = 9¶

REMOTE_VALIDATE_FAILED = 13¶

UNCLASSIFY = 1000¶

UNEXPECT_RESULT = 10¶

USER_IS_INVALID = 11¶

ZONE_IS_INVALID = 12¶

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:

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.

It represents a record in cloudns system.

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

as_dict()¶

pretty_print()¶: print record in a human readable format.

static pretty_print_status(status)¶

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(zone, 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:: zone: zone name 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

static create_zone(passport, token, zone_name)¶

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¶