def emit_help(self, classes=False):
"""Yield the help-lines for each Configurable class in self.classes.
If classes=False (the default), only flags and aliases are printed.
"""
for l in self.emit_description():
yield l
for l in self.emit_subcommands_help():
yield l
for l in self.emit_options_help():
yield l
if classes:
help_classes = self._classes_with_config_traits()
if help_classes:
yield "Class options"
yield "============="
for p in wrap_paragraphs(self.keyvalue_description):
yield p
yield ''
for cls in help_classes:
yield cls.class_get_help()
yield ''
for l in self.emit_examples():
yield l
for l in self.emit_help_epilogue(classes):
yield l
def class_get_trait_help(cls, trait, inst=None, helptext=None):
"""Get the helptext string for a single trait.
:param inst:
If given, it's current trait values will be used in place of
the class default.
:param helptext:
If not given, uses the `help` attribute of the current trait.
"""
assert inst is None or isinstance(inst, cls)
lines = []
header = f"--{cls.__name__}.{trait.name}"
if isinstance(trait, (Container, Dict)):
multiplicity = trait.metadata.get("multiplicity", "append")
if isinstance(trait, Dict):
sample_value = "<key-1>=<value-1>"
else:
sample_value = "<%s-item-1>" % trait.__class__.__name__.lower()
if multiplicity == "append":
header = f"{header}={sample_value}..."
else:
header = f"{header} {sample_value}..."
else:
header = f"{header}=<{trait.__class__.__name__}>"
# header = "--%s.%s=<%s>" % (cls.__name__, trait.name, trait.__class__.__name__)
lines.append(header)
if helptext is None:
helptext = trait.help
if helptext != "":
helptext = "\n".join(wrap_paragraphs(helptext, 76))
lines.append(indent(helptext))
if "Enum" in trait.__class__.__name__:
# include Enum choices
lines.append(indent("Choices: %s" % trait.info()))
if inst is not None:
lines.append(indent(f"Current: {getattr(inst, trait.name)!r}"))
else:
try:
dvr = trait.default_value_repr()
except Exception:
dvr = None # ignore defaults we can't construct
if dvr is not None:
if len(dvr) > 64:
dvr = dvr[:61] + "..."
lines.append(indent("Default: %s" % dvr))
return "\n".join(lines)
def class_get_trait_help(cls, trait, inst=None, helptext=None):
"""Get the helptext string for a single trait.
:param inst:
If given, it's current trait values will be used in place of
the class default.
:param helptext:
If not given, uses the `help` attribute of the current trait.
"""
assert inst is None or isinstance(inst, cls)
lines = []
header = "--%s.%s" % (cls.__name__, trait.name)
if isinstance(trait, (Container, Dict)):
multiplicity = trait.metadata.get('multiplicity', 'append')
if isinstance(trait, Dict):
sample_value = '<key-1>=<value-1>'
else:
sample_value = '<%s-item-1>' % trait.__class__.__name__.lower()
if multiplicity == 'append':
header = "%s=%s..." % (header, sample_value)
else:
header = "%s %s..." % (header, sample_value)
else:
header = '%s=<%s>' % (header, trait.__class__.__name__)
#header = "--%s.%s=<%s>" % (cls.__name__, trait.name, trait.__class__.__name__)
lines.append(header)
if helptext is None:
helptext = trait.help
if helptext != '':
helptext = '\n'.join(wrap_paragraphs(helptext, 76))
lines.append(indent(helptext))
if 'Enum' in trait.__class__.__name__:
# include Enum choices
lines.append(indent('Choices: %s' % trait.info()))
if inst is not None:
lines.append(indent("Current: %r" % (getattr(inst, trait.name), )))
else:
try:
dvr = trait.default_value_repr()
except Exception:
dvr = None # ignore defaults we can't construct
if dvr is not None:
if len(dvr) > 64:
dvr = dvr[:61] + "..."
lines.append(indent("Default: %s" % dvr))
return '\n'.join(lines)
def emit_options_help(self):
"""Yield the lines for the options part of the help."""
if not self.flags and not self.aliases:
return
header = "Options"
yield header
yield "=" * len(header)
for p in wrap_paragraphs(self.option_description):
yield p
yield ""
yield from self.emit_flag_help()
yield from self.emit_alias_help()
yield ""
def emit_options_help(self):
"""Yield the lines for the options part of the help."""
if not self.flags and not self.aliases:
return
header = 'Options'
yield header
yield '=' * len(header)
for p in wrap_paragraphs(self.option_description):
yield p
yield ''
for l in self.emit_flag_help():
yield l
for l in self.emit_alias_help():
yield l
yield ''
def emit_subcommands_help(self):
"""Yield the lines for the subcommand part of the help."""
if not self.subcommands:
return
header = "Subcommands"
yield header
yield "=" * len(header)
for p in wrap_paragraphs(self.subcommand_description.format(app=self.name)):
yield p
yield ""
for subc, (_, help) in self.subcommands.items():
yield subc
if help:
yield indent(dedent(help.strip()))
yield ""
def c(s):
"""return a commented, wrapped block."""
s = "\n\n".join(wrap_paragraphs(s, 78))
return "## " + s.replace("\n", "\n# ")
def c(s):
"""return a commented, wrapped block."""
s = '\n\n'.join(wrap_paragraphs(s, 78))
return '## ' + s.replace('\n', '\n# ')
def emit_description(self):
"""Yield lines with the application description."""
for p in wrap_paragraphs(self.description or self.__doc__):
yield p
yield ''