More documentation.

plugins/dns_api/api.py

@@ -11,16 +11,67 @@ class ApiDnsManager():
     name = None
 
     def get_domains(self):
+        """
+        List all domains managed by the dns api.
+
+        :return: List of domains
+        :rtype: list
+        """
+
         raise NotImplementedError
 
     def get_records(self, domain):
+        """
+        List all records from a given domain.
+
+        :param domain: the domain, like example.com
+        :type domain: basestring
+        :return: List of records with details (TTL, name, type, etc...)
+        :rtype: list
+        """
+
         raise NotImplementedError
 
     def add_record(self, fqdn, record):
+        """
+        Add a new record to a given domain.
+
+        :param fqdn: the domain, like example.com
+        :type fqdn: basestring
+        :param record: the record to add, with all details (TTL, name, type, etc...)
+        :type record: Record object
+        :return: status of the request and message
+        :rtype: tuple
+        """
+
         raise NotImplementedError
 
     def update_record(self, fqdn, record):
+        """
+        Update a record from a given domain with new values.
+
+        :param fqdn: the domain, like example.com
+        :type fqdn: basestring
+        :param record: the record to add, with all details (TTL, name, type, etc...)
+        :type record: Record object
+        :return: status of the request and message
+        :rtype: tuple
+        """
+
         raise NotImplementedError
 
-    def delete_record(self, fqdn, name):
+    def delete_record(self, fqdn, rtype, name):
+        """
+        Delete a record from a given domain.
+
+        :param fqdn: the domain, like example.com
+        :type fqdn: basestring
+        :param rtype: type of the DNS entry, like CNAME or AAAA
+        :type rtype: basestring
+        :param name: the record name, like test (to delete the entry test.example.com)
+        :type name: basestring
+        :return: status of the request and message
+        :rtype: tuple
+        """
+
         raise NotImplementedError

plugins/dns_api/manager.py

@@ -2,27 +2,76 @@
 import aj
 
 class Domain:
+    """Basic class for a DNS entry within a given fqdn."""
 
     def __init__(self, fqdn, manager):
+        """
+
+        :param fqdn: the domain, e.g. like exmaple.com
+        :type fqdn: basestring
+        :param manager: the domain manager instance
+        :type manager: DomainManager
+        """
+
         self.fqdn = fqdn
         self.mgr = manager
         self.api = manager.api_provider
         self.records = []
 
     def get_records(self):
+        """
+        List all records from self.fqdn.
+
+        :return: List of records with details (TTL, name, type, etc...)
+        :rtype: list
+        """
+
         self.api.get_records(self)
 
     def add_record(self, record):
+        """
+        Add a new record to self.fqdn.
+
+        :param record: the record to add, with all details (TTL, name, type, etc...)
+        :type record: Record object
+        :return: status of the request and message
+        :rtype: tuple
+        """
+
         return self.api.add_record(self.fqdn, record)
 
     def update_record(self, record):
+        """
+        Update a record from self.fqdn with new values.
+
+        :param record: the record to add, with all details (TTL, name, type, etc...)
+        :type record: Record object
+        :return: status of the request and message
+        :rtype: tuple
+        """
+
         return self.api.update_record(self.fqdn, record)
 
     def delete_record(self, rtype, name):
+        """
+        Delete a record from self.fqdn.
+
+        :param rtype: type of the DNS entry, like CNAME or AAAA
+        :type rtype: basestring
+        :param name: the record name, like test (to delete the entry test.example.com)
+        :type name: basestring
+        :return: status of the request and message
+        :rtype: tuple
+        """
+
         return self.api.delete_record(self.fqdn, rtype, name)
 
 
 class DomainManager:
+    """
+    Select the configured provider, provide an access to the api and manage
+    all domains objects.
+    """
 
     def __init__(self, context):
         self.context = context
@@ -36,8 +85,5 @@ def __init__(self, context):
         self.domains = {}
 
     def load(self):
-        self.get_domains()
-
-    def get_domains(self):
         for domain in self.api_provider.get_domains():
             self.domains[domain] = Domain(domain, self)

plugins/dns_api/views.py

@@ -17,18 +17,44 @@ def __init__(self, context):
     @get(r'/api/dns_api/domains')
     @endpoint(api=True)
     def handle_api_dns_list_domains(self, http_context):
+        """
+        List all available domains.
+
+        :return: list of domains and provider name
+        :rtype: tuple
+        """
         self.mgr.load()
         return list(self.mgr.domains.keys()), self.mgr.api_provider.name
 
     @get(r'/api/dns_api/domain/(?P<fqdn>[\w\.]+)/records')
     @endpoint(api=True)
     def handle_api_dns_list_records(self, http_context, fqdn):
+        """
+        List records from a given domain.
+
+        :param fqdn: the domain, like example.com
+        :type fqdn: basestring
+        :return: list of dict, one dict per record
+        :rtype: list
+        """
+
         self.mgr.domains[fqdn].get_records()
         return [asdict(r) for r in self.mgr.domains[fqdn].records]
 
     @post(r'/api/dns_api/domain/(?P<fqdn>[\w\.]+)/records/(?P<name>.*)')
     @endpoint(api=True)
     def handle_api_dns_post_record(self, http_context, fqdn, name):
+        """
+        Add a record to a domain.
+
+        :param fqdn: the domain, like example.com
+        :type fqdn: basestring
+        :param name: name of the record
+        :type name: basestring
+        :return: Status of the request
+        :rtype: tuple
+        """
+
         record = Record (
             name,
             http_context.json_body()['ttl'],
@@ -40,6 +66,17 @@ def handle_api_dns_post_record(self, http_context, fqdn, name):
     @put(r'/api/dns_api/domain/(?P<fqdn>[\w\.]+)/records/(?P<name>.*)')
     @endpoint(api=True)
     def handle_api_dns_put_record(self, http_context, fqdn, name):
+        """
+        Update a record to a domain.
+
+        :param fqdn: the domain, like example.com
+        :type fqdn: basestring
+        :param name: name of the record
+        :type name: basestring
+        :return: Status of the request
+        :rtype: tuple
+        """
+
         record = Record (
             name,
             http_context.json_body()['ttl'],
@@ -51,4 +88,18 @@ def handle_api_dns_put_record(self, http_context, fqdn, name):
     @delete(r'/api/dns_api/domain/(?P<fqdn>[\w\.]+)/records/(?P<rtype>[A-Z]*)/(?P<name>.*)')
     @endpoint(api=True)
     def handle_api_dns_delete_record(self, http_context, fqdn, rtype, name):
+        """
+        Delete a record to a domain.
+
+        :param fqdn: the domain, like example.com
+        :type fqdn: basestring
+        :param rtype: the DNS type, like AAAA, to avoid deleting all entries
+        with given name
+        :type rtype: basestring
+        :param name: name of the record
+        :type name: basestring
+        :return: Status of the request
+        :rtype: tuple
+        """
+
         return self.mgr.domains[fqdn].delete_record(rtype, name)