New command syntax

[pslacerda]

I would love to define commands like this to get automatic object completion and automated usage help.

@pm.extend2
def nearby_aminoacids_similarity(
  sel1: Selection,
  sel2: Selection,
  polymer1: Selection="polymer",
  polymer2: Selection="polymer",
  radius: float=4.0,
  verbose: bool=True
):
  """
  DESCRIPTION
    Do foo tasks based on the arguments.

  OPTIONS
    sel1:  selection of first object
    sel2: selection of second object
    ...
  """   

[speleo3]

I like this suggestion. Something similar exists already: cmd.extendaa. Using type-annotations looks nicer of course.

What do you mean by "automated usage help"?

[pslacerda]

With this Python 3 syntax is possible to pretty format the help automatically with HTML:

USAGE
  nearby_aminoacids_similarity sel1, sel2, [polymer1='polymer'], [polymer2='polymer'], ...

Is also possible to use the annotated function as parser so boolean or float types are automatically converted to boolean or float instead of string. For me it looks a very convenient syntax.

cmd.extendaa nowdays looks very ugly but the idea is very much the same: extends beharviour only wrapping cmd.extends.

[pslacerda]

For hobby I modified some open source to parse PyMOL docstrings. I was seriously dreaming about a full featured help usage.

Merged despite status: https://github.com/rr-/docstring_parser/pull/5

With a object model for command help and signature then a full featured help could be achieved.

[pslacerda]

class Selection(str):
  pass

class Boolean(bool):
  def __init__(self, v):
    x = v in ['True', 'true', 'T', 't', 'Yes', 'yes', 'Y', 'y', '1']
    super().__init__(x)

@pm.extend
@pm.autocomplete(    # or autocomplete(OBJECT_LIST, OBJECT_LIST)
  sel1=OBJECT_LIST,
  sel2=OBJECT_LIST
)
def nearby_aminoacids_similarity(
  sel1: Selection,
  sel2: Selection,
  polymer1: Selection="polymer",
  polymer2: Selection="polymer",
  radius: float=4.0,
  verbose: Boolean=True
):
  """
  DESCRIPTION
    Do foo tasks based on the arguments.

  OPTIONS
    sel1:  selection of first object
    sel2: selection of second object
    ...
  """

Is a better syntax. Note that I'm not using typing. The help could print a table of typed arguments followed by the description.