commit 50a2f4a12857e43cbe7435c0e36c52044d750d54
parent 1b658eb4cfbd21235fa8f0b9d8d4b4fafd83978d
Author: rexxnor <rexxnor+gnunet@brief.li>
Date: Sun, 27 Jan 2019 11:36:22 +0100
updated docstrings
Diffstat:
1 file changed, 32 insertions(+), 15 deletions(-)
diff --git 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,
