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

[André Erdmann]

commit:     68b95b0e8adfd900ed53330d1e2d5c90f8260efb
Author:     André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Jul  6 22:13:51 2012 +0000
Commit:     André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Jul  6 22:13:51 2012 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=68b95b0e

config: add descriptions to the entry map

	modified:   roverlay/config/entrymap.py
	new file:   roverlay/config/entryutil.py

---
 roverlay/config/entrymap.py  |  170 ++++++++++++++++++++++++++++++++----------
 roverlay/config/entryutil.py |   44 +++++++++++
 2 files changed, 175 insertions(+), 39 deletions(-)

diff --git a/roverlay/config/entrymap.py b/roverlay/config/entrymap.py
index f8987cf..60e1766 100644
--- a/roverlay/config/entrymap.py
+++ b/roverlay/config/entrymap.py
@@ -35,6 +35,7 @@
 
 fs_file    = 'fs_file'
 fs_abslist = 'slist:fs_abs'
+yesno      = 'yesno'
 
 # often (>1) used entry dicts (it's ok to share a ref to those dicts
 #  'cause CONFIG_ENTRY_MAP won't be modified)
@@ -50,61 +51,112 @@ LOG_LEVEL  = frozenset ((
 
 is_log_level = { 'choices' : LOG_LEVEL, 'flags' : CAPSLOCK }
 
+
 only_vtype = lambda x : { 'value_type': x }
 
 CONFIG_ENTRY_MAP = dict (
 
 	# == logging ==
 
-	log_enabled     = is_yesno,
-	log_level       = is_log_level,
+	log_enabled = dict (
+		value_type  = yesno,
+		description = "enable/disable logging",
+	),
+	log_level = dict (
+		desc = "global log level, choices are {}.".format (
+			', '.join ( LOG_LEVEL )
+		),
+		**is_log_level
+	),
 	#log_format      = None, # there's no global log format
-	log_date_format = '',
+	log_date_format = dict (
+		desc = "date format, example: '%F %H:%M:%S'.",
+	),
 
 	# used in depres listener modules
-	log_file_resolved     = is_fs_file,
-	log_file_unresolvable = is_fs_file,
+	log_file_resolved = dict (
+		value_type  = fs_file,
+		description = '''NOT IN USE.
+			file where resolved dep strings will be written to.
+		''',
+	),
+	log_file_unresolvable = dict (
+		value_type  = fs_file,
+		description = '''file where unresolved dependency strings
+			will be written to
+		'''
+	),
 
 	# === logging to console ===
 
-	log_console_enabled = is_yesno,
+	log_console_enabled = dict (
+		value_type  = yesno,
+		description = "enable/disable logging to stdout/stderr",
+	),
 	log_console         = 'log_console_enabled',
 
-	log_console_level   = is_log_level,
+	log_console_level   = dict (
+		desc = "log level for console logging.",
+		**is_log_level
+	),
 	log_level_console   = 'log_console_level',
 
 	log_console_stream  = None, # option not configurable
 
-	log_console_format  = '',
+	log_console_format  = dict (
+		desc = '''console logging format,
+			example: '%(levelname)-7s [%(name)s] %(message)s'
+		''',
+	),
 	log_format_console  = 'log_console_format',
 
 	# === logging to file ===
 
-	log_file_enabled = is_yesno,
+	log_file_enabled = dict (
+		value_type  = yesno,
+		description = "enable/disable logging to file",
+	),
 
-	log_file         = dict (
+	log_file = dict (
 		# setting path to LOG.FILE.file to avoid collision with LOG.FILE.*
-		path       = [ 'LOG', 'FILE', 'file' ],
-		value_type = fs_file,
+		path        = [ 'LOG', 'FILE', 'file' ],
+		value_type  = fs_file,
+		description = "log file to write",
 	),
 
-	log_file_level = is_log_level,
+	log_file_level = dict (
+		desc = "log level for file logging",
+		**is_log_level
+	),
 	log_level_file = 'log_file_level',
 
-	log_file_rotate       = is_yesno,
+	log_file_rotate       = dict (
+		value_type  = yesno,
+		description = "enable/disable log file rotating (per script run)",
+	),
 	log_file_rotate_count = dict (
-		path       = [ 'LOG', 'FILE', 'rotate_count' ],
-		value_type = 'int',
+		path        = [ 'LOG', 'FILE', 'rotate_count' ],
+		value_type  = 'int',
+		description = "number of rotated log files to keep",
 	),
 
-	log_file_format = '',
+	log_file_format = dict (
+		desc = '''file logging format,
+			example: '%(asctime)s %(levelname)-8s %(name)-10s: %(message)s'
+		'''
+	),
 	log_format_file = 'log_file_format',
 
-	log_file_buffered        = is_yesno,
+	log_file_buffered = dict (
+		value_type  = yesno,
+		description = "buffer log entries before writing them to file",
+	),
+
 	log_file_buffer_count    = 'log_file_buffer_capacity',
 	log_file_buffer_capacity = dict (
-		path       = [ 'LOG', 'FILE', 'buffer_capacity' ],
-		value_type = 'int',
+		path        = [ 'LOG', 'FILE', 'buffer_capacity' ],
+		value_type  = 'int',
+		description = "max number of log entries to buffer",
 	),
 
 
@@ -122,22 +174,40 @@ CONFIG_ENTRY_MAP = dict (
 	# == overlay ==
 
 	# FIXME key is not in use
-	ebuild_header    = is_fs_file,
+	ebuild_header = dict (
+		value_type  = fs_file,
+		description = '''NOT IN USE.
+			ebuild header file that will be included in every created ebuild.
+		''',
+	),
 
-	overlay_category = '', # e.g. 'sci-R'
-	overlay_dir      = only_vtype ( 'fs_abs:fs_dir' ),
+	overlay_category = dict (
+		desc = "overlay category to use for created ebuilds, e.g. 'sci-R'.",
+	),
+	overlay_dir = dict (
+		value_type = 'fs_abs:fs_dir',
+		description = '''overlay root directory where the
+			ebuilds, profiles/ dir, etc. will be written to.
+		'''
+	),
 
 	overlay_eclass = dict (
-		path       = [ 'OVERLAY', 'eclass_files' ],
-		value_type = fs_abslist,
+		path        = [ 'OVERLAY', 'eclass_files' ],
+		value_type  = fs_abslist,
+		description = '''eclass files to import into the overlay.
+			Automatically inherited in ebuilds.
+		''',
 	),
 
-	overlay_name = '',
+	overlay_name = dict (
+		desc = "overlay name, e.g. 'R-Overlay'.",
+	),
 
 	# ebuild is used to create Manifest files
 	ebuild_prog = dict (
-		path       = [ 'TOOLS', 'ebuild_prog' ],
-		value_type = 'fs_path',
+		path        = [ 'TOOLS', 'ebuild_prog' ],
+		value_type  = 'fs_path',
+		description = "name of/path to the ebuild executable",
 	),
 
 	# * alias
@@ -151,18 +221,25 @@ CONFIG_ENTRY_MAP = dict (
 	# the distfiles root directory
 	#  this is where repos create their own DISTDIR as sub directory unless
 	#  they specify another location
-	distfiles_root = only_vtype ( 'fs_dir' ),
+	distfiles_root = dict (
+		value_type  = 'fs_dir',
+		description = '''distfiles root,
+			repos will create their distdirs in this directory.
+		''',
+	),
 
 	# the repo config file(s)
 	repo_config_files = dict (
-		path       = [ 'REPO', 'config_files' ],
-		value_type = fs_abslist,
+		path        = [ 'REPO', 'config_files' ],
+		value_type  = fs_abslist,
+		description = 'list of repo config files',
 	),
 
 	# this option is used to limit bandwidth usage while running rsync
 	rsync_bwlimit = dict (
-		path       = [ 'rsync_bwlimit' ],
-		value_type = 'int',
+		path        = [ 'rsync_bwlimit' ],
+		value_type  = 'int',
+		description = "max average rsync bandwidth usage (in kilobytes/second)"
 	),
 
 	# * alias
@@ -178,8 +255,9 @@ CONFIG_ENTRY_MAP = dict (
 
 	# the list of simple dep rule files
 	simple_rules_files = dict (
-		path       = [ 'DEPRES', 'SIMPLE_RULES', 'files' ],
-		value_type = fs_abslist,
+		path        = [ 'DEPRES', 'SIMPLE_RULES', 'files' ],
+		value_type  = fs_abslist,
+		description = "list of dependency rule files",
 	),
 
 	# * alias
@@ -191,15 +269,19 @@ CONFIG_ENTRY_MAP = dict (
 	# == description reader ==
 
 	field_definition_file = dict (
-		path       = [ 'DESCRIPTION', 'field_definition_file' ],
-		value_type = fs_file,
+		path        = [ 'DESCRIPTION', 'field_definition_file' ],
+		value_type  = fs_file,
+		description = "config file that controls DESCRIPTION file reading",
 	),
 
 	# * for debugging
 	# if set: write _all_ description files to dir/<package_filename>
 	description_descfiles_dir = dict (
-		path       = [ 'DESCRIPTION', 'descfiles_dir' ],
-		value_type = 'fs_abs:fs_dir',
+		path        = [ 'DESCRIPTION', 'descfiles_dir' ],
+		value_type  = 'fs_abs:fs_dir',
+		description = '''if set: write description files (read from tarballs)
+			into this directory. Leave blank / comment out to disable.
+		'''
 	),
 
 	# * alias
@@ -213,3 +295,13 @@ CONFIG_ENTRY_MAP = dict (
 del fs_file, fs_abslist, is_fs_file, is_yesno, is_log_level, \
 	CAPSLOCK, LOG_LEVEL, only_vtype
 
+def prune_description():
+	for entry in CONFIG_ENTRY_MAP.values():
+		if isinstance ( entry, dict ):
+
+			if 'description' in entry:
+				del entry ['description']
+			elif 'desc' in entry:
+				del entry ['desc']
+
+

diff --git a/roverlay/config/entryutil.py b/roverlay/config/entryutil.py
new file mode 100644
index 0000000..dfa7647
--- /dev/null
+++ b/roverlay/config/entryutil.py
@@ -0,0 +1,44 @@
+import re
+import textwrap
+
+from roverlay.config.entrymap import CONFIG_ENTRY_MAP
+
+def _iter_entries():
+	for entry_key, entry in CONFIG_ENTRY_MAP.items():
+		name = entry_key.upper()
+		if entry is None:
+			# entry is disabled
+			pass
+		elif isinstance ( entry, dict ):
+			if 'description' in entry:
+				yield ( name, entry ['description'] )
+			elif 'desc' in entry:
+				yield ( name, entry ['desc'] )
+			else:
+				yield ( name, )
+		elif isinstance ( entry, str ) and entry:
+			yield ( name, "alias to " + entry.upper() )
+		else:
+			yield ( name, )
+
+
+def list_entries ( newline_after_entry=True ):
+	wrapper = textwrap.TextWrapper (
+		initial_indent    = 2 * ' ',
+		subsequent_indent = 3 * ' ',
+		#width = 75,
+	)
+	remove_ws = re.compile ( "\s+" )
+	wrap = wrapper.wrap
+
+	lines = list()
+	for entry in sorted ( _iter_entries(), key = lambda x : x[0] ):
+		lines.append ( entry [0] )
+		if len ( entry ) > 1:
+			lines.extend ( wrap ( remove_ws.sub ( ' ', entry [1] ) ) )
+
+		if newline_after_entry:
+			lines.append ( '' )
+
+	return '\n'.join ( lines )
+