[GNUnet-SVN] [ascension] 47/57: updated docstrings

[gnunet]

This is an automated email from the git hooks/post-receive script.

ng0 pushed a commit to branch master
in repository ascension.

commit 50a2f4a12857e43cbe7435c0e36c52044d750d54
Author: rexxnor <address@hidden>
AuthorDate: Sun Jan 27 11:36:22 2019 +0100

    updated docstrings
---
 ascension/ascension.py | 47 ++++++++++++++++++++++++++++++++---------------
 1 file changed, 32 insertions(+), 15 deletions(-)

diff --git a/ascension/ascension.py b/ascension/ascension.py
index c937553..9fbd3e3 100644
--- a/ascension/ascension.py
+++ b/ascension/ascension.py
@@ -56,7 +56,7 @@ GNUNET_ZONE_CREATION_COMMAND = 'gnunet-identity'
 GNUNET_NAMESTORE_COMMAND = 'gnunet-namestore'
 GNUNET_GNS_COMMAND = 'gnunet-gns'
 GNUNET_ARM_COMMAND = 'gnunet-arm'
-# TODO find better solution for allowed protocols
+# TODO find better solution for allowed protocols in SRV records
 SUPPORTED_PROTOCOLS = {'_tcp': 6, '_udp': 17}
 # TODO find better solution for ignoring DNSSEC record types
 SUPPORTED_RECORD_TYPES = [
@@ -73,15 +73,16 @@ class Ascender():
         if cls.domain == '.':
             cls.domain = cls.domain[:-1]
         cls.port = int(port)
-        cls.soa = None
         cls.transferns = transferns
+        cls.soa = None
         cls.zone = None
         cls.zonegenerator = None
 
     @classmethod
     def initial_zone_transfer(cls, serial=None):
         """
-        Transfer and initialize the zone
+        Initialize the zone transfer generator
+        :param serial: The serial to base the transfer on
         """
         if serial:
             cls.zonegenerator = dns.query.xfr(cls.transferns,
@@ -110,6 +111,9 @@ class Ascender():
     def get_current_serial(cls, domain, resolver=None):
         """
         Gets the current serial for a given zone
+        :param domain: Domain to query for in DNS
+        :param resolver: Nameserver to query in DNS, defaults to None
+        :returns: Serial of the zones SOA record
         """
         # SOA is different if taken directly from SOA record
         # compared to AXFR/IXFR - changed to respect this
@@ -166,7 +170,7 @@ class Ascender():
             cls.soa = cls.get_zone_soa(cls.zone)
         elif zoneserial == currentserial:
             logging.info("zone is up to date")
-        # should be unnecessary but AXFR SOA might not equal to direct SOA
+        # should be unnecessary but AXFR SOA might not be equal to direct SOA
         else:
             # because it runs as a daemon, ignore this case but log it
             logging.warning("SOA serial is bigger than zone serial?")
@@ -176,6 +180,8 @@ class Ascender():
     def add_records_to_gns(cls, flags="n"):
         """
         Extracts records from zone and adds them to GNS
+        :param flags: Flag to set in GNS, defaults to n (no flags)
+        :raises AttributeError: When getting incomplete data
         """
         logging.info("Starting to add records into GNS...")
 
@@ -312,11 +318,12 @@ class Ascender():
     @staticmethod
     def transform_to_gns_format(record, rdtype, zonename, label):
         """
-        Teansforms value of record to gnunet compatible format
+        Transforms value of record to GNS compatible format
         :param record: record to transform
         :param rdtype: record value to transform
         :param zonename: name of the zone to add to
         :param label: label under which the record is stored
+        :returns: a tuple consisting of the new rdtype, the label and value
         """
         value = str(record)
         if rdtype == 'SOA':
@@ -390,7 +397,8 @@ class Ascender():
     @classmethod
     def get_zone_serial(cls):
         """
-        Extracts the current serial from a given zone
+        Fetches the zones serial from GNS
+        :returns: serial of the SOA record in GNS
         """
         try:
             # this would also work but does not check if record/zone expired
@@ -416,7 +424,8 @@ class Ascender():
     @classmethod
     def get_soa_refresh_time(cls):
         """
-        Extracts the current serial from the current soa
+        Extracts the current serial from the class SOA
+        :returns: refresh time of the current SOA record
         """
         ttlpattern = re.compile(r'.+\s\d+,(\d+),\d+,\d+,\d+', re.M)
         return re.findall(ttlpattern, cls.soa)[0]
@@ -424,7 +433,8 @@ class Ascender():
     @classmethod
     def get_zone_refresh_time(cls):
         """
-        Extracts the current serial from a given zone
+        Extracts the current refresh time of the zone from GNS
+        :returns: refresh time of the current SOA record
         """
         try:
             serial = sp.check_output([GNUNET_GNS_COMMAND,
@@ -444,7 +454,8 @@ class Ascender():
     @classmethod
     def get_zone_retry_time(cls):
         """
-        Extracts the current serial from a given zone
+        Extracts the current retry time of the zone from GNS
+        :returns: retry time of the current SOA record
         """
         try:
             serial = sp.check_output([GNUNET_GNS_COMMAND,
@@ -464,20 +475,23 @@ class Ascender():
     @staticmethod
     def get_zone_soa(zone):
         """
-        Fetches soa record from zone
+        Fetches soa record from zone a given zone
+        :param zone: A dnspython zone
+        :returns: SOA record of given zone
         """
-        ret = None
+        soa = None
         for soarecord in zone.iterate_rdatas(rdtype=dns.rdatatype.SOA):
             if str(soarecord[0]) == '@':
-                ret = soarecord
-        return ret
+                soa = soarecord
+        return soa
 
     @staticmethod
     def add_soa_record_to_gns(record, zonename):
         """
         Adds a SOA record to GNS
+        :param record: The record to add
+        :param zonename: The zone to which to add the record
         """
-        # needs to be added in any case
         _, ttl, rdata = record
         zonetuple = str(rdata).split(' ')
         domain = zonename
@@ -506,6 +520,9 @@ class Ascender():
     def check_if_record_exists_in_zone(record, zonename):
         """
         Checks if the given record exists in GNS
+        :param record: The record to check for
+        :param zonename: The zone in which to look up the record
+        :returns: True on existance, False otherwise
         """
         dnsname, _, rdata = record
         rtype_str = str(dns.rdatatype.to_text(rdata.rdtype))
@@ -523,7 +540,7 @@ class Ascender():
         """
         Creates the zone in zonestring and returns pkey
         :param zonestring: The label name of the zone
-        :returns pkey: gnunet pkey of the zone
+        :returns: gnunet pkey of the zone
         """
         try:
             ret = sp.run([GNUNET_ZONE_CREATION_COMMAND,

-- 
To stop receiving notification emails like this one, please contact
address@hidden