def print_help(self, classes=False):
"""Print the help for each Configurable class in self.classes.
If classes=False (the default), only flags and aliases are printed.
"""
self.print_description()
self.print_subcommands()
self.print_options()
if classes:
help_classes = self._classes_with_config_traits()
if help_classes:
print("Class options")
print("=============")
for p in wrap_paragraphs(self.keyvalue_description):
print(p)
print()
for cls in help_classes:
cls.class_print_help()
print()
else:
print("To see all available configurables, use `--help-all`")
print()
self.print_examples()
def _make_trait_help(has_traits, trait):
from ipython_genutils.text import wrap_paragraphs
classes = _classes_yamling.get()
cls = type(has_traits)
if classes:
defining_class = cls._defining_class(trait, classes)
else:
defining_class = cls
if defining_class is cls:
help_lines = ['',
'%s %s %s' % ('#' * 4, trait.name, '#' * 4)]
help_lines.extend(wrap_paragraphs(trait.help, 78))
help_lines.append('Type: ' + trait.info())
if 'Enum' in type(trait).__name__:
help_lines.append('Choices: %s' % trait.info())
default_value = trait.default()
if default_value:
default_repr = ydumps(trait.default(), trait_help=False)
if default_repr.count('\n') > 1 and default_repr[0] != '\n':
default_repr = tw.indent('\n' + default_repr, ' ' * 9)
help_lines.append('Default: %s' % default_repr)
else:
# Trait appears multiple times and isn't defined here.
# Truncate help to first line + "See also Original.trait"
if trait.help:
help_lines.append(trait.help.split('\n', 1)[0])
help_lines.append('See also: %s.%s' % (defining_class.__name__, trait.name))
return '\n'.join(help_lines)
def print_subcommands(self):
"""Print the subcommand part of the help."""
## Overridden, to print "default" sub-cmd.
if not self.subcommands:
return
lines = ["Subcommands"]
lines.append('-' * len(lines[0]))
lines.append('')
for p in wrap_paragraphs(
self.subcommand_description.format(app=self.name)):
lines.append(p)
lines.append('')
for subc, (cls, hlp) in self.subcommands.items():
if self.default_subcmd == subc:
subc = '%s[*]' % subc
lines.append(subc)
if hlp:
lines.append(indent(dedent(hlp.strip())))
if self.default_subcmd:
lines.append('')
lines.append(
"""Note: The asterisk '[*]' marks the "default" sub-command to run when none specified."""
)
lines.append('')
print(os.linesep.join(lines))
def class_get_trait_help(cls, trait, inst=None):
"""Get the help string for a single trait.
If `inst` is given, it's current trait values will be used in place of
the class default.
"""
assert inst is None or isinstance(inst, cls)
lines = []
header = "--%s.%s=<%s>" % (cls.__name__, trait.name,
trait.__class__.__name__)
lines.append(header)
if inst is not None:
lines.append(indent('Current: %r' % getattr(inst, trait.name), 4))
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, 4))
if 'Enum' in trait.__class__.__name__:
# include Enum choices
lines.append(indent('Choices: %r' % (trait.values, )))
help = trait.help
if help != '':
help = '\n'.join(wrap_paragraphs(help, 76))
lines.append(indent(help, 4))
return '\n'.join(lines)
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 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 print_help(self, classes=False):
"""Print the help for each Configurable class in self.classes.
If classes=False (the default), only flags and aliases are printed.
"""
self.print_description()
self.print_subcommands()
self.print_options()
if classes:
help_classes = self.classes
if help_classes:
print("Class parameters")
print("----------------")
print()
for p in wrap_paragraphs(self.keyvalue_description):
print(p)
print()
for cls in help_classes:
cls.class_print_help()
print()
else:
print("To see all available configurables, use `--help-all`")
print()
self.print_examples()
def class_get_trait_help(cls, trait, inst=None):
"""Get the help string for a single trait.
If `inst` is given, it's current trait values will be used in place of
the class default.
"""
assert inst is None or isinstance(inst, cls)
lines = []
header = "--%s.%s=<%s>" % (cls.__name__, trait.name, trait.__class__.__name__)
lines.append(header)
if inst is not None:
lines.append(indent('Current: %r' % getattr(inst, trait.name), 4))
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, 4))
if 'Enum' in trait.__class__.__name__:
# include Enum choices
lines.append(indent('Choices: %r' % (trait.values,)))
help = trait.help
if help != '':
help = '\n'.join(wrap_paragraphs(help, 76))
lines.append(indent(help, 4))
return '\n'.join(lines)
def selector(ne, cls):
from ipython_genutils.text import wrap_paragraphs
help_lines = []
base_classes = ', '.join(p.__name__ for p in cls.__bases__)
help_lines.append(u'%s(%s)' % (cls.__name__, base_classes))
help_lines.append(len(help_lines[0]) * u'-')
cls_desc = getattr(cls, 'description', None)
if not isinstance(cls_desc, str):
cls_desc = cls.__doc__
if cls_desc:
help_lines.extend(wrap_paragraphs(cls_desc))
help_lines.append('')
try:
txt = cls.examples.default_value.strip()
if txt:
help_lines.append("Examples")
help_lines.append("--------")
help_lines.append(trtc.indent(trtc.dedent(txt)))
help_lines.append('')
except AttributeError:
pass
return '\n'.join(help_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, 4))
if 'Enum' in trait.__class__.__name__:
# include Enum choices
lines.append(indent('Choices: %s' % trait.info()))
env_var = trait.metadata.get('envvar')
if env_var:
only = '' if trait.metadata.get('config') else '(only)'
env_info = 'Environment variable%s: %s' % (only, env_var)
lines.append(indent(env_info, 4))
if inst is not None:
lines.append(indent('Current: %r' % getattr(inst, trait.name), 4))
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, 4))
return '\n'.join(lines)
def print_options(self):
if not self.flags and not self.aliases:
return
lines = ['Options']
lines.append('=' * len(lines[0]))
for p in wrap_paragraphs(self.option_description):
lines.append(p)
lines.append('')
print(os.linesep.join(lines))
self.print_flag_help()
self.print_alias_help()
print()
def print_options(self):
if not self.flags and not self.aliases:
return
lines = ['Options']
lines.append('=' * len(lines[0]))
for p in wrap_paragraphs(self.option_description):
lines.append(p)
lines.append('')
print(os.linesep.join(lines))
self.print_flag_help()
self.print_alias_help()
print()
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, 4))
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), 4))
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, 4))
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 ''
for l in self.emit_flag_help():
yield l
for l in self.emit_alias_help():
yield l
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, (cls, help) in self.subcommands.items():
yield subc
if help:
yield indent(dedent(help.strip()))
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, (cls, help) in self.subcommands.items():
yield subc
if help:
yield indent(dedent(help.strip()))
yield ''
def print_subcommands(self):
"""Print the subcommand part of the help."""
if not self.subcommands:
return
lines = ["Subcommands"]
lines.append('=' * len(lines[0]))
for p in wrap_paragraphs(self.subcommand_description.format(
app=self.name)):
lines.append(p)
lines.append('')
for subc, (cls, help) in self.subcommands.items():
lines.append(subc)
if help:
lines.append(indent(dedent(help.strip())))
lines.append('')
print(os.linesep.join(lines))
def print_subcommands(self):
"""Print the subcommand part of the help."""
if not self.subcommands:
return
lines = ["Subcommands"]
lines.append('=' * len(lines[0]))
for p in wrap_paragraphs(
self.subcommand_description.format(app=self.name)):
lines.append(p)
lines.append('')
for subc, (cls, help) in self.subcommands.items():
lines.append(subc)
if help:
lines.append(indent(dedent(help.strip())))
lines.append('')
print(os.linesep.join(lines))
def _make_commit_message(self,
*projects: pvproject.Project,
is_release=False):
from ipython_genutils.text import indent, wrap_paragraphs
sub_summary = ', '.join(
prj.interp(prj.summary_interped(is_release)) # type: ignore # none
for prj in projects)
summary = self.interp(self.message_summary, sub_summary=sub_summary)
text_lines: List[str] = []
for prj in projects:
if prj.message_body:
text_lines.append('- %s' % prj.pname)
text_lines.append(indent(wrap_paragraphs(prj.message_body), 2))
sub_body = '\n'.join(text_lines).strip()
body = self.interp(self.message_body, sub_body=sub_body)
return '%s\n\n%s' % (summary, body)
def c(s):
"""return a commented, wrapped block."""
s = '\n\n'.join(wrap_paragraphs(s, 78))
return '# ' + s.replace('\n', '\n# ')
def print_description(self):
"""Print the application description."""
for p in wrap_paragraphs(self.description):
print(p)
print()
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 ''
def emit_description(self):
"""Yield lines with the application description."""
for p in wrap_paragraphs(self.description or self.__doc__):
yield p
yield ''
def print_description(self):
"""Print the application description."""
for p in wrap_paragraphs(self.description or self.__doc__):
print(p)
print()
def _make_comment(s):
"""return a commented, wrapped block."""
from ipython_genutils.text import wrap_paragraphs
return '\n \n '.join(wrap_paragraphs(s, 78)) + '\n '
def c(s):
"""return a commented, wrapped block."""
s = "\n\n".join(wrap_paragraphs(s, 78))
return "# " + s.replace("\n", "\n# ")
