Support for callable objects in usage test. Refactor of usage text.

PiperOrigin-RevId: 260041306
Change-Id: Id14ddd3a935627a068ff4f4e3523e9cd9d90ce89

Author: dbieber

fire/completion.py

@@ -281,7 +281,18 @@ def _FishScript(name, commands, default_options=None):
   )
 
 
-def MemberVisible(component, name, member, verbose):
+def GetClassAttrsDict(component):
+  """Gets the attributes of the component class, as a dict with name keys."""
+  if not inspect.isclass(component):
+    return None
+  class_attrs_list = inspect.classify_class_attrs(component)
+  return {
+      class_attr.name: class_attr
+      for class_attr in class_attrs_list
+  }
+
+
+def MemberVisible(component, name, member, class_attrs=None, verbose=False):
   """Returns whether a member should be included in auto-completion or help.
 
   Determines whether a member of an object with the specified name should be
@@ -297,6 +308,8 @@ def MemberVisible(component, name, member, verbose):
     component: The component containing the member.
     name: The name of the member.
     member: The member itself.
+    class_attrs: (optional) If component is a class, provide this as:
+      GetClassAttrsDict(component). If not provided, it will be computed.
     verbose: Whether to include private members.
   Returns
     A boolean value indicating whether the member should be included.
@@ -310,6 +323,13 @@ def MemberVisible(component, name, member, verbose):
   if inspect.ismodule(member) and member is six:
     # TODO(dbieber): Determine more generally which modules to hide.
     return False
+  if inspect.isclass(component):
+    # If class_attrs has not been provided, compute it.
+    if class_attrs is None:
+      class_attrs = GetClassAttrsDict(class_attrs)
+    class_attr = class_attrs.get(name)
+    if class_attr and class_attr.kind == 'method':
+      return False
   if (six.PY2 and inspect.isfunction(component)
       and name in ('func_closure', 'func_code', 'func_defaults',
                    'func_dict', 'func_doc', 'func_globals', 'func_name')):
@@ -322,14 +342,20 @@ def MemberVisible(component, name, member, verbose):
   return True  # Default to including the member
 
 
-def _Members(component, verbose=False):
+def VisibleMembers(component, class_attrs=None, verbose=False):
   """Returns a list of the members of the given component.
 
   If verbose is True, then members starting with _ (normally ignored) are
   included.
 
   Args:
     component: The component whose members to list.
+    class_attrs: (optional) If component is a class, you may provide this as:
+      GetClassAttrsDict(component). If not provided, it will be computed.
+      If provided, this determines how class members will be treated for
+      visibility. In particular, methods are generally hidden for
+      non-instantiated classes, but if you wish them to be shown (e.g. for
+      completion scripts) then pass in a different class_attr for them.
     verbose: Whether to include private members.
   Returns:
     A list of tuples (member_name, member) of all members of the component.
@@ -339,10 +365,13 @@ def _Members(component, verbose=False):
   else:
     members = inspect.getmembers(component)
 
+  # If class_attrs has not been provided, compute it.
+  if class_attrs is None:
+    class_attrs = GetClassAttrsDict(component)
   return [
-      (member_name, member)
-      for member_name, member in members
-      if MemberVisible(component, member_name, member, verbose)
+      (member_name, member) for member_name, member in members
+      if MemberVisible(component, member_name, member, class_attrs=class_attrs,
+                       verbose=verbose)
   ]
 
 
@@ -386,7 +415,7 @@ def Completions(component, verbose=False):
 
   return [
       _FormatForCommand(member_name)
-      for member_name, unused_member in _Members(component, verbose)
+      for member_name, _ in VisibleMembers(component, verbose=verbose)
   ]
 
 
@@ -427,15 +456,17 @@ def _Commands(component, depth=3):
     Only traverses the member DAG up to a depth of depth.
   """
   if inspect.isroutine(component) or inspect.isclass(component):
-    for completion in Completions(component):
+    for completion in Completions(component, verbose=False):
       yield (completion,)
   if inspect.isroutine(component):
     return  # Don't descend into routines.
 
   if depth < 1:
     return
 
-  for member_name, member in _Members(component):
+  # By setting class_attrs={} we don't hide methods in completion.
+  for member_name, member in VisibleMembers(component, class_attrs={},
+                                            verbose=False):
     # TODO(dbieber): Also skip components we've already seen.
     member_name = _FormatForCommand(member_name)
 

fire/core.py

@@ -306,8 +306,12 @@ def _DictAsString(result, verbose=False):
   # We need to do 2 iterations over the items in the result dict
   # 1) Getting visible items and the longest key for output formatting
   # 2) Actually construct the output lines
-  result_visible = {key: value for key, value in result.items()
-                    if completion.MemberVisible(result, key, value, verbose)}
+  class_attrs = completion.GetClassAttrsDict(result)
+  result_visible = {
+      key: value for key, value in result.items()
+      if completion.MemberVisible(result, key, value,
+                                  class_attrs=class_attrs, verbose=verbose)
+  }
 
   if not result_visible:
     return '{}'
@@ -317,7 +321,8 @@ def _DictAsString(result, verbose=False):
 
   lines = []
   for key, value in result.items():
-    if completion.MemberVisible(result, key, value, verbose):
+    if completion.MemberVisible(result, key, value, class_attrs=class_attrs,
+                                verbose=verbose):
       line = format_string.format(key=str(key) + ':',
                                   value=_OneLineResult(value))
       lines.append(line)

fire/helptext.py

@@ -33,8 +33,6 @@
 from __future__ import division
 from __future__ import print_function
 
-import inspect
-
 from fire import completion
 from fire import custom_descriptions
 from fire import decorators
@@ -319,7 +317,7 @@ def _GetActionsGroupedByKind(component, verbose=False):
   values = ActionGroup(name='value', plural='values')
   indexes = ActionGroup(name='index', plural='indexes')
 
-  members = completion._Members(component, verbose)  # pylint: disable=protected-access
+  members = completion.VisibleMembers(component, verbose=verbose)
   for member_name, member in members:
     member_name = str(member_name)
     if value_types.IsGroup(member):
@@ -456,14 +454,7 @@ def _NewChoicesSection(name, choices):
 
 
 def UsageText(component, trace=None, verbose=False):
-  if inspect.isroutine(component) or inspect.isclass(component):
-    return UsageTextForFunction(component, trace, verbose)
-  else:
-    return UsageTextForObject(component, trace, verbose)
-
-
-def UsageTextForFunction(component, trace=None, verbose=False):
-  """Returns usage text for function objects.
+  """Returns usage text for the given component.
 
   Args:
     component: The component to determine the usage text for.
@@ -473,13 +464,12 @@ def UsageTextForFunction(component, trace=None, verbose=False):
   Returns:
     String suitable for display in an error screen.
   """
-  del verbose  # Unused.
-
-  output_template = """Usage: {current_command} {args_and_flags}
+  output_template = """Usage: {continued_command}
 {availability_lines}
 For detailed information on this command, run:
-  {current_command}{hyphen_hyphen} --help"""
+  {help_command}"""
 
+  # Get the command so far:
   if trace:
     command = trace.GetCommand()
     needs_separating_hyphen_hyphen = trace.NeedsSeparatingHyphenHyphen()
@@ -490,13 +480,67 @@ def UsageTextForFunction(component, trace=None, verbose=False):
   if not command:
     command = ''
 
+  # Build the continuations for the command:
+  continued_command = command
+
   spec = inspectutils.GetFullArgSpec(component)
+  metadata = decorators.GetMetadata(component)
+
+  # Usage for objects.
+  actions_grouped_by_kind = _GetActionsGroupedByKind(component, verbose=verbose)
+  possible_actions = _GetPossibleActions(actions_grouped_by_kind)
+
+  continuations = []
+  if possible_actions:
+    continuations.append(_GetPossibleActionsUsageString(possible_actions))
+
+  availability_lines = _UsageAvailabilityLines(actions_grouped_by_kind)
+
+  if callable(component):
+    callable_items = _GetCallableUsageItems(spec, metadata)
+    continuations.append(' '.join(callable_items))
+    availability_lines.extend(_GetCallableAvailabilityLines(spec))
+
+  if continuations:
+    continued_command += ' ' + ' | '.join(continuations)
+  help_command = (
+      command
+      + (' -- ' if needs_separating_hyphen_hyphen else ' ')
+      + '--help'
+  )
+
+  return output_template.format(
+      continued_command=continued_command,
+      availability_lines=''.join(availability_lines),
+      help_command=help_command)
+
+
+def _GetPossibleActionsUsageString(possible_actions):
+  if possible_actions:
+    return '<{actions}>'.format(actions='|'.join(possible_actions))
+  return None
+
+
+def _UsageAvailabilityLines(actions_grouped_by_kind):
+  availability_lines = []
+  for action_group in actions_grouped_by_kind:
+    if action_group.members:
+      availability_line = _CreateAvailabilityLine(
+          header='available {plural}:'.format(plural=action_group.plural),
+          items=action_group.names
+      )
+      availability_lines.append(availability_line)
+  return availability_lines
+
+
+def _GetCallableUsageItems(spec, metadata):
+  """A list of elements that comprise the usage summary for a callable."""
   args_with_no_defaults = spec.args[:len(spec.args) - len(spec.defaults)]
   args_with_defaults = spec.args[len(spec.args) - len(spec.defaults):]
 
   # Check if positional args are allowed. If not, show flag syntax for args.
-  metadata = decorators.GetMetadata(component)
   accepts_positional_args = metadata.get(decorators.ACCEPTS_POSITIONAL_ARGS)
+
   if not accepts_positional_args:
     items = ['--{arg}={upper}'.format(arg=arg, upper=arg.upper())
              for arg in args_with_no_defaults]
@@ -507,93 +551,38 @@ def UsageTextForFunction(component, trace=None, verbose=False):
   if args_with_defaults or spec.kwonlyargs or spec.varkw:
     items.append('<flags>')
 
+  if spec.varargs:
+    items.append('[{varargs}]...'.format(varargs=spec.varargs.upper()))
+
+  return items
+
+
+def _GetCallableAvailabilityLines(spec):
+  """The list of availability lines for a callable for use in a usage string."""
+  args_with_defaults = spec.args[len(spec.args) - len(spec.defaults):]
+
+  # TODO(dbieber): Handle args_with_no_defaults if not accepts_positional_args.
   optional_flags = [('--' + flag) for flag in args_with_defaults]
   required_flags = [('--' + flag) for flag in spec.kwonlyargs]
 
   # Flags section:
   availability_lines = []
   if optional_flags:
     availability_lines.append(
-        _CreateAvailabilityLine(header='Optional flags:', items=optional_flags,
-                                header_indent=0))
+        _CreateAvailabilityLine(header='optional flags:', items=optional_flags,
+                                header_indent=2))
   if required_flags:
     availability_lines.append(
-        _CreateAvailabilityLine(header='Required flags:', items=required_flags,
-                                header_indent=0))
+        _CreateAvailabilityLine(header='required flags:', items=required_flags,
+                                header_indent=2))
   if spec.varkw:
-    additional_flags = ('Additional flags are accepted.'
+    additional_flags = ('additional flags are accepted'
                         if optional_flags or required_flags else
-                        'Flags are accepted.')
-    availability_lines.append(additional_flags + '\n')
-
-  if availability_lines:
-    # Start the section with blank lines.
-    availability_lines.insert(0, '\n')
-
-  if spec.varargs:
-    items.append('[{varargs}]...'.format(varargs=spec.varargs.upper()))
-
-  args_and_flags = ' '.join(items)
-
-  hyphen_hyphen = ' --' if needs_separating_hyphen_hyphen else ''
-
-  return output_template.format(
-      current_command=command,
-      args_and_flags=args_and_flags,
-      availability_lines=''.join(availability_lines),
-      hyphen_hyphen=hyphen_hyphen)
-
-
-def UsageTextForObject(component, trace=None, verbose=False):
-  """Returns the usage text for the error screen for an object.
-
-  Constructs the usage text for the error screen to inform the user about how
-  to use the current component.
-
-  Args:
-    component: The component to determine the usage text for.
-    trace: The Fire trace object containing all metadata of current execution.
-    verbose: Whether to include private members in the usage text.
-  Returns:
-    String suitable for display in error screen.
-  """
-  output_template = """Usage: {current_command}{possible_actions}
-{availability_lines}
-For detailed information on this command, run:
-  {current_command} --help"""
-  if trace:
-    command = trace.GetCommand()
-  else:
-    command = None
-
-  if not command:
-    command = ''
-
-  actions_grouped_by_kind = _GetActionsGroupedByKind(component, verbose=verbose)
-
-  possible_actions = []
-  availability_lines = []
-  for action_group in actions_grouped_by_kind:
-    if action_group.members:
-      possible_actions.append(action_group.name)
-      availability_line = _CreateAvailabilityLine(
-          header='available {plural}:'.format(plural=action_group.plural),
-          items=action_group.names
-      )
-      availability_lines.append(availability_line)
-
-  if possible_actions:
-    possible_actions_string = ' <{actions}>'.format(
-        actions='|'.join(possible_actions))
-  else:
-    possible_actions_string = ''
-
-  availability_lines_string = ''.join(availability_lines)
-
-  return output_template.format(
-      current_command=command,
-      possible_actions=possible_actions_string,
-      availability_lines=availability_lines_string)
+                        'flags are accepted')
+    availability_lines.append(
+        _CreateAvailabilityLine(header=additional_flags, items=[],
+                                header_indent=2))
+  return availability_lines
 
 
 def _CreateAvailabilityLine(header, items,