[gentoo-commits] proj/R_overlay:master commit in: roverlay/

["André Erdmann" <dywi@mailerd.de>]

commit:     2857235f05980e0ad98351850c1422993305c6e6
Author:     André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Thu May 31 18:22:45 2012 +0000
Commit:     André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Thu May 31 18:22:45 2012 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=2857235f

roverlay, 2012-05-31:
	* basic logging
	** replaced some errors cases by log entries
	* started with the config module

---
 roverlay/__init__.py          |   19 ++++
 roverlay/config.py            |   60 +++++++++++++
 roverlay/descriptionfields.py |  121 ++++++++++++++++++++++++++
 roverlay/ebuild.py            |   96 +++++++++++++++------
 roverlay/ebuildjob.py         |   38 ++++++---
 roverlay/fileio.py            |  186 +++++++++++++++++++++--------------------
 6 files changed, 394 insertions(+), 126 deletions(-)

diff --git a/roverlay/__init__.py b/roverlay/__init__.py
index 863ab2b..b1557ef 100644
--- a/roverlay/__init__.py
+++ b/roverlay/__init__.py
@@ -2,4 +2,23 @@
 # Copyright 2006-2012 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
 
+import logging
+
+logging.basicConfig (
+	level=logging.DEBUG,
+	filename='roverlay.log',
+	filemode='a',
+	format='%(asctime)s %(levelname)-8s %(name)-14s -- %(message)s',
+	datefmt='%F %H:%M:%S'
+)
+
+# add console output to the logger
+ch = logging.StreamHandler()
+ch.setLevel ( logging.INFO )
+ch.setFormatter (
+	logging.Formatter  ( '%(levelname)-8s %(name)-14s -- %(message)s' )
+)
+logging.getLogger().addHandler ( ch )
+del ch
+
 VERSION = "0.0-pre1"

diff --git a/roverlay/config.py b/roverlay/config.py
new file mode 100644
index 0000000..248fc22
--- /dev/null
+++ b/roverlay/config.py
@@ -0,0 +1,60 @@
+# R overlay -- config module
+# Copyright 2006-2012 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+
+import sys
+
+from roverlay import descriptionfields
+
+try:
+	import configparser
+except ImportError:
+	import ConfigParser as configparser
+
+def access():
+	return ConfigTree() if ConfigTree.instance is None else ConfigTree.instance
+
+class InitialLogger:
+
+	def __init__ ( self ):
+		self.debug     = lambda x : sys.stderr.write ( "DBG  " + str ( x ) + "\n" )
+		self.info      = lambda x : sys.stderr.write ( "INFO " + str ( x ) + "\n" )
+		self.warning   = lambda x : sys.stderr.write ( "WARN " + str ( x ) + "\n" )
+		self.error     = lambda x : sys.stderr.write ( "ERR  " + str ( x ) + "\n" )
+		self.critical  = lambda x : sys.stderr.write ( "CRIT " + str ( x ) + "\n" )
+		self.exception = lambda x : sys.stderr.write ( "EXC! " + str ( x ) + "\n" )
+
+class ConfigTree:
+	# static access to the first created ConfigTree
+	instance = None
+
+	def __init__ ( self ):
+		if ConfigTree.instance is None:
+			ConfigTree.instance = self
+
+		self.logger = InitialLogger()
+
+		self.parser = dict()
+
+
+	def load_field_definition ( self, def_file, lenient=False ):
+		if not 'field_def' in self.parser:
+			self.parser ['field_def'] = configparser.SafeConfigParser ( allow_no_value=True )
+
+		try:
+			self.logger.debug ( "Reading description field definition file " + def_file + "." )
+			if lenient:
+				self.parser ['field_def'] . read ( def_file )
+			else:
+				fh = open ( def_file, 'r' )
+				self.parser ['field_def'] . readfp ( fh )
+				if fh:
+					fh.close()
+		except IOError as err:
+			self.logger.exception ( err )
+			raise
+		except configparser.MissingSectionHeaderError as mshe:
+			self.logger.exception ( mshe )
+			raise
+
+

diff --git a/roverlay/descriptionfields.py b/roverlay/descriptionfields.py
new file mode 100644
index 0000000..9c028c2
--- /dev/null
+++ b/roverlay/descriptionfields.py
@@ -0,0 +1,121 @@
+# R overlay -- description fields
+# Copyright 2006-2012 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+
+
+# split from tmpconst / fileio to make configuration possible, but TODO
+
+class DescriptionField:
+
+	def __init__ ( self, name ):
+		if not name:
+			raise Exception ( "description field name is empty." )
+
+		self.name = name
+
+
+
+	def get_name ( self ):
+		return self.name
+
+	def add_flag ( self, flag, lowercase=True ):
+		if not hasattr ( self, flags ):
+			self.flags = set ()
+
+		self.flags.add ( flag, flag.lower() if lowercase else flag )
+
+		return None
+
+
+	def del_flag ( self, flag ):
+		if hasattr ( self, flags ):
+			self.flags.discard ( flag )
+		return None
+
+
+	def add_alias ( self, alias, alias_type='withcase' ):
+		if not hasattr ( self, aliases ):
+			self.aliases = dict ()
+
+		to_add = dict (
+			withcase = alias,
+			nocase   = alias.lower(),
+		) [alias_type]
+
+
+		if not alias_type in self.aliases:
+			self.aliases [alias_type] = set ()
+
+		self.aliases [alias_type] . add ( to_add )
+
+		return None
+
+
+
+	def add_simple_alias ( self, alias, withcase=True ):
+		if withcase:
+			return self.add_alias ( alias, alias_type='withcase' )
+		else:
+			return self.add_alias ( alias, alias_type='nocase' )
+
+
+
+	def get_default_value ( self ):
+		if hasattr ( self, 'default_value' ):
+			return self.default_value
+		else:
+			return None
+
+
+	def get ( self, key, fallback_value=None ):
+		if hasattr ( self, key ):
+			return self.key
+		else:
+			return fallback_value
+
+	def matches ( self, field_identifier ):
+		return bool ( self.name == field_identifier ) if field_identifier else False
+
+	def matches_alias ( self, field_identifier ):
+
+		if not field_identifier:
+			return False
+		if not hasattr ( self, aliases ):
+			return False
+
+		if 'withcase' in self.aliases:
+			if field_identifier in self.aliases ['withcase']:
+				return True
+
+		if 'nocase' in self.aliases:
+			field_id_lower = field_identifier.lower()
+			if field_id_lower in self.aliases ['nocase']:
+				return True
+
+	def has_flag ( self, flag, lowercase=True ):
+		if not hasattr ( self, flags ):
+			return False
+
+		return bool ( (flag.lower() if lowercase else flag) in self.flags )
+
+class DescriptionFields:
+
+	def __init__ ( self ):
+		fields = dict ()
+
+	def add ( self, desc_field ):
+		if desc_field:
+			if isinstance ( desc_field, DescriptionField ):
+				fields [desc_field.get_name()] = desc_field
+				return 1
+			elif isinstance ( desc_field, str ):
+				fields [desc_field] = DescriptionField ( desc_field )
+				return 2
+
+		return 0
+
+	def get ( self, field_name ):
+		return self.fields [field_name] if field_name in self.fields else None
+
+	# ... TODO
+

diff --git a/roverlay/ebuild.py b/roverlay/ebuild.py
index 8c960a2..1634ef3 100644
--- a/roverlay/ebuild.py
+++ b/roverlay/ebuild.py
@@ -6,16 +6,31 @@ class Ebuild:
 	# could move this to const
 	EBUILD_INDENT = "\t"
 
-	def __init__ ( self ):
+	ADD_REMAP = {
+		# pkg vs package
+		'package_name'     : 'pkg_name',
+		'package_version'  : 'pkg_version',
+		'package_revision' : 'pkg_revision',
+		# TITLE is in DESCRIPTION
+		'TITLE'            : 'DESCRIPTION',
+	}
+
+	def __init__ ( self, logger ):
 		"""Initializes an Ebuild.
 		This is an abstraction layer between the verified + calculated data
 		and the ebuild data, which can be written into a file / stdout / stdin.
 		Most functions here assume that everything is fine when it reaches them.
+
+		arguments:
+		* logger -- logger for this Ebuild
 		"""
 
+		self.logger = logger
+
 		# elements in ebuild_data are either a str or a list of str
 		self._data = dict ()
 		self._ebuild_lines = None
+		self._ebuild_name = None
 
 	# --- end of __init__ (...) ---
 
@@ -24,6 +39,8 @@ class Ebuild:
 		This saves some memory but makes this Ebuild read-only.
 		"""
 		if self._ebuild_lines:
+			# determine the ebuild name first
+			self._ebuild_name = self.suggest_name()
 			del self._data
 			self._data = None
 
@@ -56,12 +73,18 @@ class Ebuild:
 
 	# --- end of prepare (...) ---
 
+	def has_ebuild ( self ):
+		"""Returns True if this object has ebuild text lines else False."""
+		return bool ( self._ebuild_lines )
+	# --- end of has_ebuild (...) ---
+
 	def add ( self, key, value, append=True ):
 		"""Adds data to this Ebuild.
 
 		arguments:
 		* key -- identifier of the data (e.g. DEPEND).
-		         May be remapped here (e.g. merging 'Title' and 'Description')
+		         May be remapped (e.g. merging 'Title' and 'Description')
+		         or even refused here
 		* value --
 		* append -- whether to append values or overwrite existing ones,
 		            defaults to True.
@@ -72,17 +95,22 @@ class Ebuild:
 			# -- todo
 			raise Exception ("Ebuild data are readonly.")
 
-		if append and key in self._data:
-			if not isinstance ( self._data [key], list ):
-				self._data [key] = [ self._data [key] ]
-
-			if isinstance ( value, list ):
-				self._data [key].extend ( value )
-			else:
-				self._data [key].append ( value )
+		_key = Ebuild.ADD_REMAP [key] if key in Ebuild.ADD_REMAP else key
 
+		if _key is None:
+			self.logger.debug ( "add (%s, %s): filtered key.", key, str ( value ) )
 		else:
-			self._data [key] = value
+			if append and _key in self._data:
+				if not isinstance ( self._data [_key], list ):
+					self._data [_key] = [ self._data [_key] ]
+
+				if isinstance ( value, list ):
+					self._data [_key].extend ( value )
+				else:
+					self._data [_key].append ( value )
+
+			else:
+				self._data [_key] = value
 
 	# --- end of add (...) ---
 
@@ -99,14 +127,12 @@ class Ebuild:
 				self.show ( fh )
 				fh.close()
 				del fh
-				return True
 			except IOError as err:
-				# ? todo
+				self.logger.exception ( err )
 				raise
 
 		else:
-				# todo log this
-				raise Exception ("cannot write ebuild")
+				self.logger.warning ( "Cannot write ebuild - it's empty! (check with has_ebuild() before calling this method.)" )
 
 	# --- end of write (...) ---
 
@@ -128,20 +154,39 @@ class Ebuild:
 
 	# --- end of show (...) ---
 
-	def suggest_name ( self, fallback_name=None ):
+	def suggest_dir_name ( self ):
+		"""Suggests a direcory name for this Ebuild."""
+		return self._data ['pkg_name'] if 'pkg_name' in self._data else self.suggest_name().partition ( '-' )
+	# --- end of suggest_dir_name (...) ---
+
+	def suggest_name ( self, fallback_name='' ):
 		"""Suggests a file name for the ebuild. This is calculated using
 		pkg_name/version/revision. Returns a fallback_name if this is not
 		possible.
 
 		arguments:
-		fallback_name -- name to return if no suggestion available, defaults to None
+		fallback_name -- name to return if no suggestion available, defaults to empty string
 		"""
 
-		if 'pkg_name' in self._data and 'pkg_version' in self._data:
-			join = [ 'pkg_name' , 'pkg_version' ]
-			if 'pkg_revision' in self._data: join.append ('pkg_revision')
+		if self._ebuild_name:
+			return self._ebuild_name
+		elif (not self._data is None) and 'pkg_name' in self._data:
+			name_components = [ self._data ['pkg_name'] ]
+
+			if 'pkg_version' in self._data:
+				name_components.append ( self._data ['pkg_version'] )
+			else:
+				# default ver
+				name_components.append ( '1.0' )
+
+			if 'pkg_revision' in self._data:
+				rev = self._data ['pkg_revision']
+
+				# omit rev == 0 and invalid revisions
+				if isinstance ( rev, int ) and rev > 0:
+					name_components.append ( 'r' + rev )
 
-			return '-' . join ( [ self._data [c] for c in join ] )
+			return '-'.join ( name_components )
 
 		else:
 			return fallback_name
@@ -316,7 +361,7 @@ class Ebuild:
 			if 'SRC_URI' in self._data:
 				add_easyvar ( ebuild_lines, "SRC_URI" )
 			else:
-				# > calculate SRC_URI using self._data ['origin']
+				# > calculate SRC_URI using self._data ['origin'] -- either here or in eclass
 				ebuild_lines.append ( make_var ( "SRC_URI" , None ) )
 				# (temporary, todo) setting restrict to fetch
 				ebuild_lines.append ( make_var ( "RESTRICT" , "fetch" ) )
@@ -345,9 +390,8 @@ class Ebuild:
 			del dep_and_use
 			return remove_newlines ( ebuild_lines )
 
-		except Exception as err:
-			# log this
-			## ..
-			raise
+		except ( ValueError, KeyError, NameError ) as err:
+			self.logger.error ( "Cannot create ebuild text lines. The error message was %s.", str ( err ) )
+			return None
 
 		# --- end of make_ebuild_lines (...) ---

diff --git a/roverlay/ebuildjob.py b/roverlay/ebuildjob.py
index 2d29643..0357e77 100644
--- a/roverlay/ebuildjob.py
+++ b/roverlay/ebuildjob.py
@@ -3,11 +3,15 @@
 # Distributed under the terms of the GNU General Public License v2
 
 import time
+import logging
+import re
 
 from roverlay.fileio import DescriptionReader
 from roverlay.ebuild import Ebuild
 
 class EbuildJob:
+	LOGGER = logging.getLogger ( 'EbuildJob' )
+
 	# move this to const / config
 	DEPENDENCY_FIELDS = {
 		'R_SUGGESTS' : [ 'Suggests' ],
@@ -43,10 +47,12 @@ class EbuildJob:
 		dep resolver 'communication channel', status codes etc.
 		"""
 
-		self.package_file = package_file
+		#self.package_file = package_file
 		self.dep_resolver = dep_resolver
 		# get description reader from args?
-		self.description_reader = DescriptionReader()
+		self.description_reader = DescriptionReader ( package_file )
+
+		self.logger = EbuildJob.LOGGER.getChild ( self.description_reader.get_log_name () )
 
 		self.ebuild = None
 
@@ -92,23 +98,29 @@ class EbuildJob:
 		"""
 
 		# TODO move hardcoded entries to config/const
+		# TODO metadata.xml creation
 
 		try:
 
 			# set status or return
 			if not self._set_status ( 'BUSY', True ): return
 
-			read_data = self.description_reader.readfile ( self.package_file )
-
-			if read_data is None:
-				# set status accordingly
+			desc = self.description_reader.get_desc ( True )
+			if desc is None:
 				self._set_status ( 'FAIL' )
-				return
+				self.logger.info ( 'Cannot create an ebuild for this package.' )
+
 
-			fileinfo  = read_data ['fileinfo']
-			desc      = read_data ['description_data']
+			fileinfo  = self.description_reader.get_fileinfo ()
+
+			ebuild = Ebuild ( self.logger.getChild ( "Ebuild" ) )
+
+			ebuild.add ( 'pkg_name', fileinfo ['package_name'] )
+			# TODO move regex to config/const
+			ebuild.add ( 'pkg_version',
+							re.sub ( '[-]{1,}', '.', fileinfo ['package_version'] )
+							)
 
-			ebuild = Ebuild()
 
 			have_description = False
 
@@ -216,7 +228,7 @@ class EbuildJob:
 
 		except Exception as any_exception:
 			# any exception means failure
-			self.status = 'FAIL'
+			self._set_status ( 'FAIL' )
 			raise
 
 	# --- end of run (...) ---
@@ -231,15 +243,19 @@ class EbuildJob:
 
 		if new_status == 'FAIL':
 			# always allowed
+			self.logger.info ( "Entering status '%s'.", new_status )
 			self.status = new_status
+			return True
 
 		if new_status and new_status in EbuildJob.STATUS_LIST:
 			# check if jumping from self.status to new_status is allowed
 			if new_status in EbuildJob.STATUS_BRANCHMAP [self.status]:
+				self.logger.debug ( "Entering status '%s'.", new_status )
 				self.status = new_status
 				return True
 
 		# default return
+		self.logger.error ( "Cannot enter status '%s'.", new_status )
 		return False
 
 	# --- end of _set_status (...) ---

diff --git a/roverlay/fileio.py b/roverlay/fileio.py
index 7c89356..5c01527 100644
--- a/roverlay/fileio.py
+++ b/roverlay/fileio.py
@@ -3,11 +3,10 @@
 # Distributed under the terms of the GNU General Public License v2
 
 import re
-import os.path
 import tarfile
+import logging
+import os.path
 
-# temporary import until logging is implemented
-from sys import stderr as logging
 
 # temporary import until config and real constants are implemented
 from roverlay import tmpconst as const
@@ -15,12 +14,70 @@ from roverlay import tmpconst as const
 class DescriptionReader:
 	"""Description Reader"""
 
-	def __init__ ( self ):
+	LOGGER = logging.getLogger ( 'DescriptionReader' )
+
+	def __init__ ( self, package_file, read_now=False ):
 		"""Initializes a DESCRIPTION file reader."""
-		pass
+
+		self.fileinfo  = self.make_fileinfo ( package_file )
+		self.logger    = DescriptionReader.LOGGER.getChild ( self.get_log_name() )
+		self.desc_data = None
+
+
+		if read_now:
+			self.run()
 
 	# --- end of __init__ (...) ---
 
+	def get_log_name ( self ):
+		try:
+			return self.fileinfo ['filename']
+		except Exception as any_exception:
+			return '__undef__'
+
+	def get_desc ( self, run_if_unset=True ):
+		if self.desc_data is None:
+			self.run ()
+
+		return self.desc_data
+	# --- end of get_desc (...) ---
+
+	def get_fileinfo ( self ):
+		return self.fileinfo
+	# --- end of get_fileinfo (...) ---
+
+	def make_fileinfo ( self, filepath ):
+		"""Returns some info about the given filepath as dict whose contents are
+			the file path, the file name ([as package_file with suffix and]
+			as filename with tarball suffix removed), the package name
+			and the package_version.
+
+		arguments:
+		* filepath --
+		"""
+
+		package_file = os.path.basename ( filepath )
+
+		filename = re.sub ( const.RPACKAGE_SUFFIX_REGEX + '$', '', package_file )
+
+		# todo move that separator to const
+		package_name, sepa, package_version = filename.partition ( '_' )
+
+		if not sepa:
+			# file name unexpected, tarball extraction will (probably) fail
+			DescriptionReader.LOGGER.error ( "unexpected file name %s.'", filename )
+
+		return dict (
+			filepath        = filepath,
+			filename        = filename,
+			package_file    = package_file,
+			package_name    = package_name,
+			#package_origin = ?,
+			package_version = package_version,
+		)
+
+	# --- end of make_fileinfo (...) ---
+
 
 	def _parse_read_data ( self, read_data ):
 		"""Verifies and parses/fixes read data.
@@ -91,44 +148,31 @@ class DescriptionReader:
 
 
 		# check for fields that allow only certain values
-		unsuitable_fields = list()
+		unsuitable_fields = dict()
 
 		for field in read_data.keys():
-			# skip _fileinfo
-			if field  != '_fileinfo':
-				if 'allowed_values' in const.DESCRIPTION_FIELD_MAP [field]:
-					if not value_in_strlist ( read_data [field],
-						const.DESCRIPTION_FIELD_MAP [field] ['allowed_values']
-					): unsuitable_fields.append ( field )
+			if 'allowed_values' in const.DESCRIPTION_FIELD_MAP [field]:
+				if not value_in_strlist (
+							read_data [field],
+							const.DESCRIPTION_FIELD_MAP [field] ['allowed_values']
+						):
+					unsuitable_fields.append [field] = read_data [field]
 
-		valid = True
-
-		if len ( missing_fields ):
-			valid = False
-
-			logging.write (
-				"Verification of mandatory fields failed, the result leading to this was: " +
-				str ( missing_fields ) + "\n"
-			)
-
-			#<raise custom exception>
-			raise Exception ("^^^look above")
-
-		if len ( unsuitable_fields ):
-			valid = False
-
-			logging.write (
-				"Some fields have values that forbid further parsing, the result leading to this was: " +
-					str ( unsuitable_fields ) + "\n"
-				)
-
-		del missing_fields
 		del field
 
+		valid = not bool ( len ( missing_fields ) or len ( unsuitable_fields ) )
+		if not valid:
+			self.logger.info ( "Cannot use R package" ) # name?
+			if len ( missing_fields ):
+				self.logger.debug ( "The following mandatory description fields are missing: %s.", str ( missing_fields ) )
+			if len ( unsuitable_fields ):
+				self.logger.debug ( "The following fields have unsuitable values: %s.", str ( unsuitable_fields ) )
+
 		return valid
+
 	# --- end of _parse_read_data (...) ---
 
-	def readfile ( self, filepath ):
+	def run ( self ):
 		"""Reads a DESCRIPTION file and returns the read data if successful, else None.
 
 		arguments:
@@ -145,40 +189,6 @@ class DescriptionReader:
 		e.g. if OS_TYPE is not unix).
 		"""
 
-		def get_fileinfo ( filepath ):
-			"""Returns some info about the given filepath as dict whose contents are
-				the file path, the file name ([as package_file with suffix and]
-				as filename with tarball suffix removed), the package name
-				and the package_version.
-
-			arguments:
-			* filepath --
-			"""
-
-			package_file = os.path.basename ( filepath )
-
-			filename = re.sub ( const.RPACKAGE_SUFFIX_REGEX + '$', '', package_file )
-
-			# todo move that separator to const
-			package_name, sepa, package_version = filename.partition ( '_' )
-
-			if not sepa:
-				# file name unexpected, tarball extraction will (probably) fail
-				#raise Exception ("file name unexpected")
-				logging.write ( "unexpected file name '" + filename + "'.\n" )
-
-			return dict (
-				filepath        = filepath,
-				filename        = filename,
-				package_file    = package_file,
-				package_name    = package_name,
-				#package_origin = ?,
-				package_version = package_version,
-			)
-
-		# --- end of get_fileinfo (...) ---
-
-
 		def make_values ( value_str, field_context=None ):
 			"""Extracts relevant data from value_str and returns them as list.
 
@@ -252,7 +262,7 @@ class DescriptionReader:
 			file is read (<pkg_name>/DESCRIPTION) or a normal file.
 			"""
 
-			logging.write ( "Starting to read file '" + str ( filepath ) + "' ...\n" )
+			self.logger.debug ( "Starting to read file '" + str ( filepath ) + "' ...\n" )
 
 			if not ( isinstance ( filepath, str ) and filepath ):
 				raise Exception ( "bad usage" )
@@ -338,16 +348,19 @@ class DescriptionReader:
 		# --- end of find_field (...) ---
 
 
+		self.desc_data = None
 		read_data = dict ()
-		fileinfo = get_fileinfo ( filepath )
 
 
 		try:
-			desc_lines = get_desc_from_file ( filepath, fileinfo ['package_name'] )
+			desc_lines = get_desc_from_file (
+				self.fileinfo ['filepath'],
+				self.fileinfo ['package_name']
+			)
 
 		except IOError as err:
-			# <todo>
-			raise
+			self.logger.exception ( err )
+			return self.desc_data
 
 
 		field_context = val = line = sline = None
@@ -393,18 +406,15 @@ class DescriptionReader:
 
 					else:
 						# useless line, skip
-						logging.write (
-							"Skipping a line, first line component (field identifier?) was: '"
-							+ line_components [0] + "'\n"
-						)
+						self.logger.info ( "Skipped a description field: '%s'.", line_components [0] )
 
 				else:
 					# reaching this branch means that
 					#  (a) line has no leading whitespace
 					#  (b) line has no separator (:)
 					# this should not occur in description files (bad syntax?)
-					logging.write ( "***" + line_components [0] + "***\n")
-					raise Exception ( "bad file" )
+					self.logger.warning ( "Unexpected line in description file: '%s'.", line_components [0] )
+
 
 				del line_components
 
@@ -412,14 +422,12 @@ class DescriptionReader:
 
 
 		if self._parse_read_data ( read_data ):
-			#logging.write ( '## success ##\n' )
-			#logging.write ( ( str ( read_data ) ) )
-			return dict (
-				fileinfo = fileinfo,
-				description_data = read_data
-			)
-		else:
-			logging.write ( '## fail ##\n' )
-			return None
+			self.logger.debug ( "Successfully read file '%s' with data = %s.",
+										self.fileinfo ['filepath'], str ( read_data )
+									)
+			self.desc_data = read_data
+
+		# get_desc() is preferred, but this method returns the desc data, too
+		return self.desc_data
 
 	# --- end of readfile (...) ---