Change in pysim[master]: card_key_provider: Documentation with sphinx / autodoc

laforge gerrit-no-reply at lists.osmocom.org
Sat Apr 3 09:35:32 UTC 2021


laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/pysim/+/23593 )


Change subject: card_key_provider: Documentation with sphinx / autodoc
......................................................................

card_key_provider: Documentation with sphinx / autodoc

Change-Id: Ia41e14d643d452d92fc8d3c2fb9c4ac9021402e9
---
M docs/library.rst
M pySim/card_key_provider.py
2 files changed, 71 insertions(+), 15 deletions(-)



  git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/93/23593/1

diff --git a/docs/library.rst b/docs/library.rst
index ae027ff..656a780 100644
--- a/docs/library.rst
+++ b/docs/library.rst
@@ -90,3 +90,9 @@
 
 .. automodule:: pySim.card_handler
    :members:
+
+pySim card_key_provider
+-----------------------
+
+.. automodule:: pySim.card_key_provider
+   :members:
diff --git a/pySim/card_key_provider.py b/pySim/card_key_provider.py
index 80f93d0..b4e1daa 100644
--- a/pySim/card_key_provider.py
+++ b/pySim/card_key_provider.py
@@ -1,5 +1,14 @@
 # coding=utf-8
-"""Abstraction of card related data that can be queried from external source."""
+"""Obtaining card parameters (mostly key data) from external source.
+
+This module contains a base class and a concrete implementation of
+obtaining card key material (or other card-individual parameters) from
+an external data source.
+
+This is used e.g. to keep PIN/PUK data in some file on disk, avoiding
+the need of manually entering the related card-individual data on every
+operation with pySim-shell.
+"""
 
 # (C) 2021 by Sysmocom s.f.m.c. GmbH
 # All Rights Reserved
@@ -23,16 +32,24 @@
 
 import csv
 
-card_key_providers = List[CardKeyProvider]
+card_key_providers = List['CardKeyProvider']
 
 class CardKeyProvider(object):
+	"""Abstract base class, not containing any concrete implementation."""
 
 	VALID_FIELD_NAMES = ['ICCID', 'ADM1', 'IMSI', 'PIN1', 'PIN2', 'PUK1', 'PUK2']
 
 	# check input parameters, but do nothing concrete yet
-	def get_data(self, fields:List[str]=[], key:str='ICCID', value:str="") -> Dict[str,str]:
-		"""abstract implementation of get_data that only verifies the function parameters"""
+	def _verify_get_data(self, fields:List[str]=[], key:str='ICCID', value:str="") -> Dict[str,str]:
+		"""Verify multiple fields for identified card.
 
+		Args:
+			fields : list of valid field names such as 'ADM1', 'PIN1', ... which are to be obtained
+			key : look-up key to identify card data, such as 'ICCID'
+			value : value for look-up key to identify card data
+		Returns:
+			dictionary of {field, value} strings for each requested field from 'fields'
+		"""
 		for f in fields:
 			if (f not in self.VALID_FIELD_NAMES):
 				raise ValueError("Requested field name '%s' is not a valid field name, valid field names are: %s" %
@@ -51,23 +68,34 @@
 		return result.get(field)
 
 	def get(self, fields:List[str], key:str, value:str) -> Dict[str,str]:
-		"""get fields from CSV file using a specified key/value pair"""
+		"""Get multiple card-individual fields for identified card.
+
+		Args:
+			fields : list of valid field names such as 'ADM1', 'PIN1', ... which are to be obtained
+			key : look-up key to identify card data, such as 'ICCID'
+			value : value for look-up key to identify card data
+		Returns:
+			dictionary of {field, value} strings for each requested field from 'fields'
+		"""
 		pass
 
 class CardKeyProviderCsv(CardKeyProvider):
-	"""card data class that allows the user to query against a specified CSV file"""
+	"""Card key provider implementation that allows to query against a specified CSV file"""
 	csv_file = None
 	filename = None
 
 	def __init__(self, filename:str):
+		"""
+		Args:
+			filename : file name (path) of CSV file containing card-individual key/data
+		"""
 		self.csv_file = open(filename, 'r')
 		if not self.csv_file:
-			raise RuntimeError("Could not open CSV-File '%s'" % filename)
+			raise RuntimeError("Could not open CSV file '%s'" % filename)
 		self.filename = filename
 
 	def get(self, fields:List[str], key:str, value:str) -> Dict[str,str]:
-		"""get fields from CSV file using a specified key/value pair"""
-		super().get_data(fields, key, value)
+		super()._verify_get_data(fields, key, value)
 
 		self.csv_file.seek(0)
 		cr = csv.DictReader(self.csv_file)
@@ -88,17 +116,31 @@
 
 
 def card_key_provider_register(provider:CardKeyProvider, provider_list=card_key_providers):
-	"""Register a new card data provider"""
+	"""Register a new card key provider.
+
+	Args:
+		provider : the to-be-registered provider
+		provider_list : override the list of providers from the global default
+	"""
 	if not isinstance(provider, CardKeyProvider):
 		raise ValueError("provider is not a card data provier")
 	provider_list.append(provider)
 
 
 def card_key_provider_get(fields, key:str, value:str, provider_list=card_key_providers) -> Dict[str,str]:
-	"""Query all registered card data providers"""
+	"""Query all registered card data providers for card-individual [key] data.
+
+	Args:
+		fields : list of valid field names such as 'ADM1', 'PIN1', ... which are to be obtained
+		key : look-up key to identify card data, such as 'ICCID'
+		value : value for look-up key to identify card data
+		provider_list : override the list of providers from the global default
+	Returns:
+		dictionary of {field, value} strings for each requested field from 'fields'
+	"""
 	for p in provider_list:
 		if not isinstance(p, CardKeyProvider):
-			raise ValueError("provider list contains provider, which is not a card data provier")
+			raise ValueError("provider list contains element which is not a card data provier")
 		result = p.get(fields, key, value)
 		if result:
 			return result
@@ -106,12 +148,20 @@
 
 
 def card_key_provider_get_field(field:str, key:str, value:str, provider_list=card_key_providers) -> Optional[str]:
-	"""Query all registered card data providers for a single field"""
+	"""Query all registered card data providers for a single field.
+
+	Args:
+		field : name valid field such as 'ADM1', 'PIN1', ... which is to be obtained
+		key : look-up key to identify card data, such as 'ICCID'
+		value : value for look-up key to identify card data
+		provider_list : override the list of providers from the global default
+	Returns:
+		dictionary of {field, value} strings for the requested field
+	"""
 	for p in provider_list:
 		if not isinstance(p, CardKeyProvider):
-			raise ValueError("provider list contains provider, which is not a card data provier")
+			raise ValueError("provider list contains element which is not a card data provier")
 		result = p.get_field(field, key, value)
 		if result:
 			return result
 	return None
-

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

Gerrit-Project: pysim
Gerrit-Branch: master
Gerrit-Change-Id: Ia41e14d643d452d92fc8d3c2fb9c4ac9021402e9
Gerrit-Change-Number: 23593
Gerrit-PatchSet: 1
Gerrit-Owner: laforge <laforge at osmocom.org>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20210403/92e69730/attachment.htm>


More information about the gerrit-log mailing list