def print_flag_help(self):
"""Print the flag part of the help."""
if not self.flags:
return
lines = []
for flags, (cfg, fhelp) in self.flags.items():
try:
if not isinstance(flags, tuple):
flags = (flags, )
flags = sorted(flags, key=len)
flags = ', '.join(
('--%s' if len(m) > 1 else '-%s') % m for m in flags)
lines.append(flags)
lines.append(indent(dedent(fhelp.strip())))
cfg_list = ' '.join('--%s.%s=%s' % (clname, prop, val)
for clname, props_dict in cfg.items()
for prop, val in props_dict.items())
cfg_txt = "Equivalent to: [%s]" % cfg_list
lines.append(indent(dedent(cfg_txt)))
except Exception as ex:
self.log.error(
'Failed collecting help-message for flag %r, due to: %s',
flags, ex)
raise
# lines.append('')
print(os.linesep.join(lines))
def print_flag_help(self):
"""Print the flag part of the help."""
if not self.flags:
return
lines = []
for flags, (cfg, fhelp) in self.flags.items():
try:
if not isinstance(flags, tuple):
flags = (flags, )
flags = sorted(flags, key=len)
flags = ', '.join(('--%s' if len(m) > 1 else '-%s') % m
for m in flags)
lines.append(flags)
lines.append(indent(dedent(fhelp.strip())))
cfg_list = ' '.join('--%s.%s=%s' %(clname, prop, val)
for clname, props_dict
in cfg.items() for prop, val in props_dict.items())
cfg_txt = "Equivalent to: [%s]" % cfg_list
lines.append(indent(dedent(cfg_txt)))
except Exception as ex:
self.log.error('Failed collecting help-message for flag %r, due to: %s',
flags, ex)
raise
# lines.append('')
print(os.linesep.join(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 run(self, *args):
"""Leaf sub-commands must inherit this instead of :meth:`start()` without invoking :func:`super()`.
:param args:
Invoked by :meth:`start()` with :attr:`extra_args`.
By default, screams about using sub-cmds, or about doing nothing!
"""
import ipython_genutils.text as tw
assert self.subcommands, "Override run() method in cmd subclasses."
if args:
subcmd_msg = "unknown sub-command `%s`!" % args[0]
else:
subcmd_msg = "sub-command is missing!"
subcmds = '\n'.join(' %10s: %s' % (k, desc)
for k, (_, desc) in self.subcommands.items())
msg = tw.dedent("""
%(cmd_chain)s: %(subcmd_msg)s
Try one of:
%(subcmds)s
%(epilogue)s""") % {
'subcmd_msg': subcmd_msg,
'cmd_chain': cmd_line_chain(self),
'subcmds': subcmds,
'epilogue': '\n'.join(self.emit_help_epilogue()),
}
raise CmdException(msg)
def rst_all_options(cls, nspace=0, prefix=None):
"""Recursively generate rST for a provided Configurable class.
:arg cls: The Configurable class.
:arg nspace: Indentation level.
:arg prefix: Prefix to use for new traits."""
lines = []
classname = cls.__name__
# Slaved options don't appear directly, but underneath their controlling enum.
slaved_options = set()
for trait in cls.class_own_traits().values():
if isinstance(trait, PairedEnum):
slaved_options.add(trait.paired_name)
for k, trait in sorted(cls.class_own_traits(config=True).items()):
typ = trait.__class__.__name__
if trait.name in slaved_options:
continue
_prefix = prefix if prefix is not None else classname
termline = "{prefix:}.\ **{suffix:}**".format(prefix=_prefix,
suffix=trait.name)
if 'Enum' in typ:
termline += ' : ' + '|'.join(repr(x) for x in trait.values)
else:
termline += ' : ' + typ
lines.append(indent(termline, nspace))
if isinstance(trait, PairedEnum):
# Find the slaved option and recurse to fill in the subtree.
dvr = trait.default_value_repr()
extra = [
"",
"Setting value implies configuration of sub-tree %s.%s:" %
(classname, trait.paired_name), ""
]
for opt, val in trait.paired_defaults.items():
extra.append("'%s':" % opt)
extra.append("")
extra.append(
rst_all_options(val,
4 + nspace,
prefix=classname + "." +
trait.paired_name))
extra = "\n".join(extra)
else:
extra = None
try:
dvr = trait.default_value_repr()
except Exception:
dvr = None
help = trait.help or 'No description'
lines.append(indent(dedent(help), 4 + nspace))
lines.append('')
lines.append(indent("Default:\n", 4 + nspace))
lines.append(indent(dvr.replace("\\n", "\\\\n"), 4 + nspace))
if extra is not None:
lines.append(indent(extra, 4 + nspace))
lines.append('')
return "\n".join(lines)
def emit_examples(self):
"""Yield lines with the usage and examples.
This usage string goes at the end of the command line help string
and should contain examples of the application's usage.
"""
if self.examples:
yield "Examples"
yield "--------"
yield ''
yield indent(dedent(self.examples.strip()))
yield ''
def print_examples(self):
"""Print usage and examples.
This usage string goes at the end of the command line help string
and should contain examples of the application's usage.
"""
if self.examples:
print("Examples")
print("--------")
print()
print(indent(dedent(self.examples.strip())))
print()
def print_flag_help(self):
"""Print the flag part of the help."""
if not self.flags:
return
lines = []
for m, (cfg, help) in self.flags.items():
prefix = '--' if len(m) > 1 else '-'
lines.append(prefix + m)
lines.append(indent(dedent(help.strip())))
# lines.append('')
print(os.linesep.join(lines))
def emit_examples(self):
"""Yield lines with the usage and examples.
This usage string goes at the end of the command line help string
and should contain examples of the application's usage.
"""
if self.examples:
yield "Examples"
yield "--------"
yield ''
yield indent(dedent(self.examples.strip()))
yield ''
def print_examples(self):
"""Print usage and examples.
This usage string goes at the end of the command line help string
and should contain examples of the application's usage.
"""
if self.examples:
print("Examples")
print("--------")
print()
print(indent(dedent(self.examples.strip())))
print()
def print_flag_help(self):
"""Print the flag part of the help."""
if not self.flags:
return
lines = []
for m, (cfg,help) in iteritems(self.flags):
prefix = '--' if len(m) > 1 else '-'
lines.append(prefix+m)
lines.append(indent(dedent(help.strip())))
# lines.append('')
print(os.linesep.join(lines))
def class_config_rst_doc(cls, trait_aliases):
"""Generate rST documentation for this class' config options.
Excludes traits defined on parent classes.
"""
lines = []
classname = cls.__name__
for k, trait in sorted(cls.class_traits(config=True).items()):
ttype = trait.__class__.__name__
fullname = classname + '.' + trait.name
lines += ['.. configtrait:: ' + fullname,
''
]
help = trait.help.rstrip() or 'No description'
lines.append(indent(dedent(help), 4) + '\n')
# Choices or type
if 'Enum' in ttype:
# include Enum choices
lines.append(indent(
':options: ' + ', '.join('``%r``' % x for x in trait.values), 4))
else:
lines.append(indent(':trait type: ' + ttype, 4))
# Default value
# Ignore boring default values like None, [] or ''
if interesting_default_value(trait.default_value):
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] + '...'
# Double up backslashes, so they get to the rendered docs
dvr = dvr.replace('\\n', '\\\\n')
lines.append(indent(':default: ``%s``' % dvr, 4))
# Command line aliases
if trait_aliases[fullname]:
fmt_aliases = format_aliases(trait_aliases[fullname])
lines.append(indent(':CLI option: ' + fmt_aliases, 4))
# Blank line
lines.append('')
return '\n'.join(lines)
def class_config_rst_doc(cls, trait_aliases):
"""Generate rST documentation for this class' config options.
Excludes traits defined on parent classes.
"""
lines = []
classname = cls.__name__
for k, trait in sorted(cls.class_traits(config=True).items()):
ttype = trait.__class__.__name__
fullname = classname + '.' + trait.name
lines += ['.. configtrait:: ' + fullname,
''
]
help = trait.help.rstrip() or 'No description'
lines.append(indent(dedent(help), 4) + '\n')
# Choices or type
if 'Enum' in ttype:
# include Enum choices
lines.append(indent(
':options: ' + ', '.join('``%r``' % x for x in trait.values), 4))
else:
lines.append(indent(':trait type: ' + ttype, 4))
# Default value
# Ignore boring default values like None, [] or ''
if interesting_default_value(trait.default_value):
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] + '...'
# Double up backslashes, so they get to the rendered docs
dvr = dvr.replace('\\n', '\\\\n')
lines.append(indent(':default: ``%s``' % dvr, 4))
# Command line aliases
if trait_aliases[fullname]:
fmt_aliases = format_aliases(trait_aliases[fullname])
lines.append(indent(':CLI option: ' + fmt_aliases, 4))
# Blank line
lines.append('')
return '\n'.join(lines)
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 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 class_config_rst_doc(cls):
"""Generate rST documentation for this class' config options.
Excludes traits defined on parent classes.
"""
lines = []
classname = cls.__name__
for k, trait in sorted(cls.class_traits(config=True).items()):
ttype = trait.__class__.__name__
termline = classname + '.' + trait.name
# Choices or type
if 'Enum' in ttype:
# include Enum choices
termline += ' : ' + '|'.join(repr(x) for x in trait.values)
else:
termline += ' : ' + ttype
lines.append(termline)
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))
# Default value
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] + '...'
# Double up backslashes, so they get to the rendered docs
dvr = dvr.replace('\\n', '\\\\n')
lines.append(indent('Default: ``%s``' % dvr, 4))
lines.append('')
help = trait.help or 'No description'
lines.append(indent(dedent(help), 4))
# Blank line
lines.append('')
return '\n'.join(lines)
def class_config_rst_doc(cls):
"""Generate rST documentation for this class' config options.
Excludes traits defined on parent classes.
"""
lines = []
classname = cls.__name__
for k, trait in sorted(cls.class_own_traits(config=True).items()):
ttype = trait.__class__.__name__
termline = classname + '.' + trait.name
# Choices or type
if 'Enum' in ttype:
# include Enum choices
termline += ' : ' + '|'.join(repr(x) for x in trait.values)
else:
termline += ' : ' + ttype
lines.append(termline)
# Default value
try:
dv = trait.get_default_value()
dvr = repr(dv)
except Exception:
dvr = dv = None # ignore defaults we can't construct
if (dv is not None) and (dvr is not None):
if len(dvr) > 64:
dvr = dvr[:61]+'...'
# Double up backslashes, so they get to the rendered docs
dvr = dvr.replace('\\n', '\\\\n')
lines.append(' Default: ``%s``' % dvr)
lines.append('')
help = trait.get_metadata('help')
if help is not None:
lines.append(indent(dedent(help), 4))
else:
lines.append(' No description')
# Blank line
lines.append('')
return '\n'.join(lines)
def class_config_rst_doc(cls):
"""Generate rST documentation for this class' config options.
Excludes traits defined on parent classes.
"""
lines = []
classname = cls.__name__
for k, trait in sorted(cls.class_own_traits(config=True).items()):
ttype = trait.__class__.__name__
termline = classname + '.' + trait.name
# Choices or type
if 'Enum' in ttype:
# include Enum choices
termline += ' : ' + '|'.join(repr(x) for x in trait.values)
else:
termline += ' : ' + ttype
lines.append(termline)
# Default value
try:
dv = trait.default_value
dvr = repr(dv)
except Exception:
dvr = dv = None # ignore defaults we can't construct
if (dv is not None) and (dvr is not None):
if len(dvr) > 64:
dvr = dvr[:61] + '...'
# Double up backslashes, so they get to the rendered docs
dvr = dvr.replace('\\n', '\\\\n')
lines.append(' Default: ``%s``' % dvr)
lines.append('')
help = trait.get_metadata('help')
if help is not None:
lines.append(indent(dedent(help), 4))
else:
lines.append(' No description')
# Blank line
lines.append('')
return '\n'.join(lines)
def class_config_rst_doc(cls):
"""Generate rST documentation for this class' config options.
Excludes traits defined on parent classes.
"""
lines = []
classname = cls.__name__
for k, trait in sorted(cls.class_own_traits(config=True).items()):
ttype = trait.__class__.__name__
termline = classname + "." + trait.name
# Choices or type
if "Enum" in ttype:
# include Enum choices
termline += " : " + "|".join(repr(x) for x in trait.values)
else:
termline += " : " + ttype
lines.append(termline)
# Default value
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] + "..."
# Double up backslashes, so they get to the rendered docs
dvr = dvr.replace("\\n", "\\\\n")
lines.append(" Default: ``%s``" % dvr)
lines.append("")
help = trait.help or "No description"
lines.append(indent(dedent(help), 4))
# Blank line
lines.append("")
return "\n".join(lines)
def generate_config_file_yaml(self, classes=None, config: trc.Config = None):
"""
generate default config file from Configurables
:param config:
If given, only what is contained there is included in generated yaml,
with help-descriptions from classes, only where class default-values
differ from the values contained in this dictionary.
"""
from ruamel.yaml.comments import CommentedMap
import ipython_genutils.text as tw
from ..utils import yamlutil as yu
classes = self.classes if classes is None else classes
config_classes = set(self._classes_with_config_traits(classes))
## Order: subclass at the top.
# Filtering needed because `order_class_hierarchy()` brings full mro().
ordered_classes = [
cls for cls in order_class_hierarchy(classes) if cls in config_classes
]
class_hiearchy = generate_class_hierarchy_text(ordered_classes)
cfg = CommentedMap()
if yu._dump_trait_help.get():
start_comment = tw.dedent("""
############################################################################
Configuration hierarchy for `%s`:
%s
############################################################################
""") % (self.root_object().name, class_hiearchy)
cfg.yaml_set_start_comment(start_comment)
for cls in ordered_classes[::
-1]: # Inverted order from title's class-list, above.
cls.class_config_yaml(cfg, config=config)
return cfg
except:
self.shell.showtraceback()
return True
else:
if self.view.block:
try:
result.get()
except:
self.shell.showtraceback()
return True
else:
result.display_outputs()
return False
def pxrun_cell(self, raw_cell, *args, **kwargs):
"""drop-in replacement for InteractiveShell.run_cell.
This executes code remotely, instead of in the local namespace.
See InteractiveShell.run_cell for details.
"""
self._px_cell = raw_cell
return self._original_run_cell(raw_cell, *args, **kwargs)
__doc__ = __doc__.format(
AUTOPX_DOC = dedent(ParallelMagics.autopx.__doc__),
PX_DOC = dedent(ParallelMagics.px.__doc__),
RESULT_DOC = dedent(ParallelMagics.result.__doc__),
CONFIG_DOC = dedent(ParallelMagics.pxconfig.__doc__),
)
self.shell.showtraceback()
return True
else:
if self.view.block:
try:
result.get()
except:
self.shell.showtraceback()
return True
else:
result.display_outputs()
return False
def pxrun_cell(self, raw_cell, *args, **kwargs):
"""drop-in replacement for InteractiveShell.run_cell.
This executes code remotely, instead of in the local namespace.
See InteractiveShell.run_cell for details.
"""
self._px_cell = raw_cell
return self._original_run_cell(raw_cell, *args, **kwargs)
__doc__ = __doc__.format(
AUTOPX_DOC=dedent(ParallelMagics.autopx.__doc__),
PX_DOC=dedent(ParallelMagics.px.__doc__),
RESULT_DOC=dedent(ParallelMagics.result.__doc__),
CONFIG_DOC=dedent(ParallelMagics.pxconfig.__doc__),
)
