"""Command registry: the HC Panel's label for a method lives on the method.
 
 A command used to be declared in two places -- the method, and a hand-written
 ``label -> bound method`` entry in HCMaps -- with nothing checking they agreed.
 Renaming the method silently emptied the panel entry, and the panel swallowed
 the resulting AttributeError, so it looked like the command simply did nothing.
 
 Now the label is a decorator on the method:
 
     @command("Replace Node")
     def replaceNode(self):
         ...
 
 and HCMaps is generated by scanning the classes. There is no second place to
 forget. Hotkeys (hc_hotkeys.json) and the XML menus still carry their own
 entries, because Houdini owns those formats -- but `symbols()` lets a check
 verify they point at commands that exist.
 
 Where a command shows up is the class it is defined on. Commands on
 HCSession and HCPane are always available; commands on a tab class appear
 whenever the current tab is an instance of it, so a method on HCTab shows
 everywhere and one on HCNetworkEditor only in network editors. Put a command
 on the narrowest class whose every instance can run it.
 
 When that varies within a class, name a predicate the same way a getter is
 named:
 
     @command("Path", state="isShowingPath", available="hasNetworkControls")
     def toggleNetworkControls(self): ...
 
 The panel leaves the command out of a tab whose predicate returns false.
 There used to be a `tabs=("HCPathTab", ...)` filter of .type() strings
 instead -- a second scoping mechanism beside the class tree, which drifted
 from it: Pin and Path were both missing from network editors because the
 list named the two types someone had in front of them at the time.
 
 A command can also describe the control the panel should draw for it. There
 are three kinds:
 
     action  -- a plain row. Enter runs the method and closes the panel.
 
     toggle  -- a row with a checkbox showing the current state. Declare the
                getter that reads it:
 
                    @command("Grid", state="isGridVisible")
                    def toggleGrid(self): ...
 
                Enter still runs the method and closes; clicking the checkbox
                runs it and leaves the panel open.
 
     choice  -- a row with a dropdown. Declare the choices and the getter; the
                method takes the chosen value:
 
                    @command("Grid Mode", state="gridMode",
                             choices=(("No Grid", "0"), ("Grid Points", "1")))
                    def setGridMode(self, mode): ...
 
                Enter opens the dropdown; picking an entry applies it and
                leaves the panel open.
 
 The getter is named, not passed, for the same reason the label is a
 decorator: it has to resolve on the same instance the method is bound to, and
 naming it lets tools/check.py verify it exists.
 """
 
 import inspect
 
 ATTR = "_hc_command"
 
 KINDS = ("action", "toggle", "choice")
 
 
 class Command:
     __slots__ = ("label", "help", "state", "choices", "available", "kind")
 
     def __init__(self, label, help=None, state=None, choices=None,
                  available=None):
         self.label = label
         self.help = help
         # Name of a method on the instance that says whether this particular
         # tab can run the command, or None when every instance of the class
         # can. hasNetworkControls() is the worked example: some tabs of the
         # plain HCTab kind have a path bar and some do not.
         self.available = available
         # Name of the method that reads the current value, on the same
         # instance the command is bound to. Its return is a bool for toggles
         # and one of the choice values for choices.
         self.state = state
         # ((label, value), ...) for choice commands.
         self.choices = tuple(tuple(c) for c in choices) if choices else None
         if self.choices is not None:
             if self.state is None:
                 raise ValueError(f"{label!r}: choices need a state getter")
             for choice in self.choices:
                 if len(choice) != 2:
                     raise ValueError(f"{label!r}: choices are (label, value) pairs")
             self.kind = "choice"
         elif self.state is not None:
             self.kind = "toggle"
         else:
             self.kind = "action"
 
     def __repr__(self):
         return f"<Command {self.label!r} {self.kind}>"
 
 
 def command(label, help=None, state=None, choices=None, available=None):
     """Expose the decorated method in the HC Panel under `label`."""
     def decorate(fn):
         setattr(fn, ATTR, Command(label, help=help, state=state,
                                   choices=choices, available=available))
         return fn
     return decorate
 
 
 def declared(cls):
     """{label: (method name, Command)} for commands on `cls`, inherited included."""
     found = {}
     for name in dir(cls):
         if name.startswith("__"):
             continue
         try:
             attr = getattr(cls, name)
         except AttributeError:
             continue
         spec = getattr(attr, ATTR, None)
         if isinstance(spec, Command):
             found[spec.label] = (name, spec)
     return found
 
 
 def asBool(value):
     """Coerce a state getter's return to a bool.
 
     Houdini prefs come back as the strings '0' and '1', and bool('0') is
     True -- which is how a checkbox would end up ticked for every toggle
     that reads a pref. Only the text of the string counts.
     """
     if isinstance(value, str):
         return value.strip().lower() not in ("", "0", "false", "off", "no")
     return bool(value)
 
 
 class Bound:
     """A command bound to an instance.
 
     Calling it runs the method, exactly like the bound method it replaces --
     HCMaps used to hand out bare bound methods and the panel just called
     them. On top of that it can read the current state for the panel's
     control, and apply a chosen value.
     """
 
     __slots__ = ("label", "spec", "instance", "method")
 
     def __init__(self, label, spec, instance, method):
         self.label = label
         self.spec = spec
         self.instance = instance
         self.method = method
 
     @property
     def kind(self):
         return self.spec.kind
 
     @property
     def choices(self):
         return self.spec.choices
 
     def __call__(self, *args, **kwargs):
         return self.method(*args, **kwargs)
 
     def state(self):
         """The current value, or None for an action.
 
         A bool for a toggle, one of the choice values for a choice. A getter
         that raises is left to raise: the panel disables the control and
         reports it, which beats a checkbox quietly showing the wrong state.
         """
         if self.spec.state is None:
             return None
         value = getattr(self.instance, self.spec.state)()
         if self.kind == "toggle":
             return asBool(value)
         return value
 
     def set(self, value):
         """Apply a choice value."""
         return self.method(value)
 
     def __repr__(self):
         return f"<Bound {self.label!r} {self.kind} on {type(self.instance).__name__}>"
 
 
 def bind(instance):
     """{label: Bound} for the commands on `instance` that apply.
 
     A command whose `available` predicate returns false on this instance is
     left out. A predicate that raises is left to raise, like a state getter:
     the caller sees the failure instead of a command quietly missing.
     """
     if instance is None:
         return {}
     bound = {}
     for label, (name, spec) in declared(type(instance)).items():
         if spec.available is not None and not getattr(instance, spec.available)():
             continue
         method = getattr(instance, name, None)
         if method is not None:
             bound[label] = Bound(label, spec, instance, method)
     return bound
 
 
 def labels(cls):
     return sorted(declared(cls))
 
 
 def verify(cls):
     """Problems with the controls declared on `cls`, as a list of strings.
 
     Empty when every state getter and availability predicate names a
     callable on the class and every choice command's method accepts the
     chosen value. tools/check.py runs this over every wrapper class.
     """
     problems = []
     for label, (name, spec) in declared(cls).items():
         for role, getter_name in (("state getter", spec.state),
                                   ("availability predicate", spec.available)):
             if getter_name is not None and not callable(getattr(cls, getter_name, None)):
                 problems.append(f"{cls.__name__}.{name} ({label!r}): "
                                 f"{role} {getter_name!r} does not exist")
         method = getattr(cls, name)
         try:
             params = [p for p in inspect.signature(method).parameters.values()
                       if p.name != "self"]
         except (TypeError, ValueError):
             continue
         required = [p for p in params if p.default is p.empty
                     and p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
         if spec.kind == "choice":
             positional = [p for p in params
                           if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
             if len(required) > 1 or not positional:
                 problems.append(f"{cls.__name__}.{name} ({label!r}): "
                                 f"a choice command takes exactly one value")
         elif required:
             problems.append(f"{cls.__name__}.{name} ({label!r}): "
                             f"the panel calls it with no arguments")
     return problems