Change in osmocom-bb[master]: trx_toolkit/data_msg.py: convert comments into docstring for methods

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

fixeria gerrit-no-reply at lists.osmocom.org
Fri Feb 26 21:28:18 UTC 2021


fixeria has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmocom-bb/+/23132 )


Change subject: trx_toolkit/data_msg.py: convert comments into docstring for methods
......................................................................

trx_toolkit/data_msg.py: convert comments into docstring for methods

Change-Id: I856b54fd1baca4ae0edd2aa59be6a76372cef667
Related: OS#4006, SYS#4895
---
M src/target/trx_toolkit/data_msg.py
1 file changed, 70 insertions(+), 42 deletions(-)



  git pull ssh://gerrit.osmocom.org:29418/osmocom-bb refs/changes/32/23132/1

diff --git a/src/target/trx_toolkit/data_msg.py b/src/target/trx_toolkit/data_msg.py
index 22818a4..15c310a 100644
--- a/src/target/trx_toolkit/data_msg.py
+++ b/src/target/trx_toolkit/data_msg.py
@@ -123,18 +123,16 @@
 	CHDR_VERSION_MAX = 0b1111
 	known_versions = [0x00, 0x01]
 
-	# Common constructor
 	def __init__(self, fn = None, tn = None, burst = None, ver = 0):
 		self.burst = burst
 		self.ver = ver
 		self.fn = fn
 		self.tn = tn
 
-	# The common header length
 	@property
 	def CHDR_LEN(self):
-		# (VER + TN) + FN
-		return 1 + 4
+		''' The common header length. '''
+		return 1 + 4 # (VER + TN) + FN
 
 	@abc.abstractmethod
 	def gen_hdr(self):
@@ -161,21 +159,22 @@
 		''' Generate a random message specific burst. '''
 		raise NotImplementedError
 
-	# Generates a random frame number
 	def rand_fn(self):
+		''' Generate a random frame number. '''
 		return random.randint(0, GSM_HYPERFRAME)
 
-	# Generates a random timeslot number
 	def rand_tn(self):
+		''' Generate a random timeslot number. '''
 		return random.randint(0, 7)
 
-	# Randomizes the message header
 	def rand_hdr(self):
+		''' Randomize the message header. '''
 		self.fn = self.rand_fn()
 		self.tn = self.rand_tn()
 
-	# Generates human-readable header description
 	def desc_hdr(self):
+		''' Generate human-readable header description. '''
+
 		result = ""
 
 		if self.ver > 0:
@@ -192,28 +191,29 @@
 
 		return result
 
-	# Converts unsigned soft-bits {254..0} to soft-bits {-127..127}
 	@staticmethod
 	def usbit2sbit(bits):
+		''' Convert unsigned soft-bits {254..0} to soft-bits {-127..127}. '''
 		return [-127 if (b == 0xff) else 127 - b for b in bits]
 
-	# Converts soft-bits {-127..127} to unsigned soft-bits {254..0}
 	@staticmethod
 	def sbit2usbit(bits):
+		''' Convert soft-bits {-127..127} to unsigned soft-bits {254..0}. '''
 		return [127 - b for b in bits]
 
-	# Converts soft-bits {-127..127} to bits {1..0}
 	@staticmethod
 	def sbit2ubit(bits):
+		''' Convert soft-bits {-127..127} to bits {1..0}. '''
 		return [int(b < 0) for b in bits]
 
-	# Converts bits {1..0} to soft-bits {-127..127}
 	@staticmethod
 	def ubit2sbit(bits):
+		''' Convert bits {1..0} to soft-bits {-127..127}. '''
 		return [-127 if b else 127 for b in bits]
 
-	# Validates the message fields (throws ValueError)
 	def validate(self):
+		''' Validate the message fields (throws ValueError). '''
+
 		if not self.ver in self.known_versions:
 			raise ValueError("Unknown TRXD header version %d" % self.ver)
 
@@ -229,8 +229,9 @@
 		if self.tn < 0 or self.tn > 7:
 			raise ValueError("TDMA time-slot %d is out of range" % self.tn)
 
-	# Generates a TRX DATA message
 	def gen_msg(self, legacy = False):
+		''' Generate a TRX DATA message. '''
+
 		# Validate all the fields
 		self.validate()
 
@@ -258,8 +259,9 @@
 
 		return buf
 
-	# Parses a TRX DATA message
 	def parse_msg(self, msg):
+		''' Parse a TRX DATA message. '''
+
 		# Make sure we have at least common header
 		if len(msg) < self.CHDR_LEN:
 			raise ValueError("Message is to short: missing common header")
@@ -317,9 +319,10 @@
 	# Specific message fields
 	pwr = None
 
-	# Calculates header length depending on its version
 	@property
 	def HDR_LEN(self):
+		''' Calculate header length depending on its version. '''
+
 		# Common header length
 		length = self.CHDR_LEN
 
@@ -331,8 +334,9 @@
 
 		return length
 
-	# Validates the message fields (throws ValueError)
 	def validate(self):
+		''' Validate the message fields (throws ValueError). '''
+
 		# Validate common fields
 		DATAMSG.validate(self)
 
@@ -350,8 +354,9 @@
 		if len(self.burst) not in (GSM_BURST_LEN, EDGE_BURST_LEN):
 			raise ValueError("Tx burst has odd length %u" % len(self.burst))
 
-	# Generates a random power level
 	def rand_pwr(self, min = None, max = None):
+		''' Generate a random power level. '''
+
 		if min is None:
 			min = self.PWR_MIN
 
@@ -360,13 +365,15 @@
 
 		return random.randint(min, max)
 
-	# Randomizes message specific header
 	def rand_hdr(self):
+		''' Randomize message specific header. '''
+
 		DATAMSG.rand_hdr(self)
 		self.pwr = self.rand_pwr()
 
-	# Generates human-readable header description
 	def desc_hdr(self):
+		''' Generate human-readable header description. '''
+
 		# Describe the common part
 		result = DATAMSG.desc_hdr(self)
 
@@ -376,8 +383,9 @@
 		# Strip useless whitespace and return
 		return result.strip()
 
-	# Generates message specific header part
 	def gen_hdr(self):
+		''' Generate message specific header part. '''
+
 		# Allocate an empty byte-array
 		buf = bytearray()
 
@@ -386,18 +394,21 @@
 
 		return buf
 
-	# Parses message specific header part
 	def parse_hdr(self, hdr):
+		''' Parse message specific header part. '''
+
 		# Parse power level
 		self.pwr = hdr[5]
 
-	# Generates message specific burst
 	def gen_burst(self):
+		''' Generate message specific burst. '''
+
 		# Copy burst 'as is'
 		return bytearray(self.burst)
 
-	# Parses message specific burst
 	def parse_burst(self, burst):
+		''' Parse message specific burst. '''
+
 		length = len(burst)
 
 		# Distinguish between GSM and EDGE
@@ -406,12 +417,13 @@
 		else:
 			self.burst = list(burst[:GSM_BURST_LEN])
 
-	# Generate a random message specific burst
 	def rand_burst(self, length = GSM_BURST_LEN):
+		''' Generate a random message specific burst. '''
 		self.burst = [random.randint(0, 1) for _ in range(length)]
 
-	# Transforms this message to TRX2L1 message
 	def gen_trx2l1(self, ver = None):
+		''' Transform this message to TRX2L1 message. '''
+
 		# Allocate a new message
 		msg = DATAMSG_TRX2L1(fn = self.fn, tn = self.tn,
 			ver = self.ver if ver is None else ver)
@@ -545,9 +557,10 @@
 	tsc = None
 	ci = None
 
-	# Calculates header length depending on its version
 	@property
 	def HDR_LEN(self):
+		''' Calculate header length depending on its version. '''
+
 		# Common header length
 		length = self.CHDR_LEN
 
@@ -586,15 +599,17 @@
 		if len(self.burst) != self.mod_type.bl:
 			raise ValueError("Rx burst has odd length %u" % len(self.burst))
 
-	# Validates the burst (throws ValueError)
 	def validate_burst(self):
+		''' Validate the burst (throws ValueError). '''
+
 		if self.ver == 0x00:
 			self._validate_burst_v0()
 		elif self.ver >= 0x01:
 			self._validate_burst_v1()
 
-	# Validates the message header fields (throws ValueError)
 	def validate(self):
+		''' Validate the message header fields (throws ValueError). '''
+
 		# Validate common fields
 		DATAMSG.validate(self)
 
@@ -641,8 +656,9 @@
 
 		self.validate_burst()
 
-	# Generates a random RSSI value
 	def rand_rssi(self, min = None, max = None):
+		''' Generate a random RSSI value. '''
+
 		if min is None:
 			min = self.RSSI_MIN
 
@@ -651,8 +667,9 @@
 
 		return random.randint(min, max)
 
-	# Generates a ToA (Time of Arrival) value
 	def rand_toa256(self, min = None, max = None):
+		''' Generate a random ToA (Time of Arrival) value. '''
+
 		if min is None:
 			min = self.TOA256_MIN
 
@@ -661,8 +678,9 @@
 
 		return random.randint(min, max)
 
-	# Randomizes message specific header
 	def rand_hdr(self):
+		''' Randomize message specific header. '''
+
 		DATAMSG.rand_hdr(self)
 		self.rssi = self.rand_rssi()
 		self.toa256 = self.rand_toa256()
@@ -678,8 +696,9 @@
 			# C/I: Carrier-to-Interference ratio
 			self.ci = random.randint(self.CI_MIN, self.CI_MAX)
 
-	# Generates human-readable header description
 	def desc_hdr(self):
+		''' Generate human-readable header description. '''
+
 		# Describe the common part
 		result = DATAMSG.desc_hdr(self)
 
@@ -705,8 +724,9 @@
 		# Strip useless whitespace and return
 		return result.strip()
 
-	# Encodes Modulation and Training Sequence info
 	def gen_mts(self):
+		''' Encode Modulation and Training Sequence info. '''
+
 		# IDLE / nope indication has no MTS info
 		if self.nope_ind:
 			return self.NOPE_IND
@@ -720,8 +740,9 @@
 
 		return mts
 
-	# Parses Modulation and Training Sequence info
 	def parse_mts(self, mts):
+		''' Parse Modulation and Training Sequence info. '''
+
 		# IDLE / nope indication has no MTS info
 		self.nope_ind = (mts & self.NOPE_IND) > 0
 		if self.nope_ind:
@@ -744,8 +765,9 @@
 			self.mod_type = Modulation.ModGMSK
 			self.tsc_set = mts & 0b11
 
-	# Generates message specific header part
 	def gen_hdr(self):
+		''' Generate message specific header part. '''
+
 		# Allocate an empty byte-array
 		buf = bytearray()
 
@@ -766,8 +788,9 @@
 
 		return buf
 
-	# Parses message specific header part
 	def parse_hdr(self, hdr):
+		''' Parse message specific header part. '''
+
 		# Parse RSSI
 		self.rssi = -(hdr[5])
 
@@ -781,16 +804,18 @@
 			# C/I: Carrier-to-Interference ratio (in centiBels)
 			self.ci = struct.unpack(">h", hdr[9:11])[0]
 
-	# Generates message specific burst
 	def gen_burst(self):
+		''' Generate message specific burst. '''
+
 		# Convert soft-bits to unsigned soft-bits
 		burst_usbits = self.sbit2usbit(self.burst)
 
 		# Encode to bytes
 		return bytearray(burst_usbits)
 
-	# Parses message specific burst for header version 0
 	def _parse_burst_v0(self, burst):
+		''' Parse message specific burst for header version 0. '''
+
 		bl = len(burst)
 
 		# We need to guess modulation by the length of burst
@@ -804,8 +829,9 @@
 
 		return burst[:self.mod_type.bl]
 
-	# Parses message specific burst
 	def parse_burst(self, burst):
+		''' Parse message specific burst. '''
+
 		burst = list(burst)
 
 		if self.ver == 0x00:
@@ -814,15 +840,17 @@
 		# Convert unsigned soft-bits to soft-bits
 		self.burst = self.usbit2sbit(burst)
 
-	# Generate a random message specific burst
 	def rand_burst(self, length = None):
+		''' Generate a random message specific burst. '''
+
 		if length is None:
 			length = self.mod_type.bl
 
 		self.burst = [random.randint(-127, 127) for _ in range(length)]
 
-	# Transforms this message to L12TRX message
 	def gen_l12trx(self, ver = None):
+		''' Transform this message to L12TRX message. '''
+
 		# Allocate a new message
 		msg = DATAMSG_L12TRX(fn = self.fn, tn = self.tn,
 			ver = self.ver if ver is None else ver)

-- 
To view, visit https://gerrit.osmocom.org/c/osmocom-bb/+/23132
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: osmocom-bb
Gerrit-Branch: master
Gerrit-Change-Id: I856b54fd1baca4ae0edd2aa59be6a76372cef667
Gerrit-Change-Number: 23132
Gerrit-PatchSet: 1
Gerrit-Owner: fixeria <vyanitskiy at sysmocom.de>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20210226/9f90198f/attachment.htm>


More information about the gerrit-log mailing list