New Command

new_command is a new API-only feature which exposes an user defined Python function as a command to other users.

In a brief

from pymol import cmd
from pathlib import Path
from typing import List, Tuple, Union, Any, Optional

Point = Tuple[float, float, float]

@cmd.new_command
def nice_tool(
    my_var: Union[int | float],
    a_point: Point,
    title: str,
    other_point: Tuple[int, int, int] = (0, 0, 0),
    dirname: Path = Path('.'),
    this_list: Optional[List[bool]] = None,
    extended_calculation: bool = True,
    old_style: Any = "anything as string",
    quiet: bool = True,  # special 'quiet=False' on command-line
    _self=cmd  # special for multi-threaded applications
):
    "A cool docstring."
    print(locals())

These code blocks ahead are sample usage of the above function.

PyMOL> nice_tool 10, 0.1 2.3 4.5, Have a nice tool, this_list=1 0 yes 0

{'my_var': 10, 'a_point': (0.1, 2.3, 4.5), 'title': 'Have a nice tool', 'other_point': (0, 0, 0), 'dirname': PosixPath('.'), 'this_list': [True, False, True, False], 'extended_calculation': True, 'old_style': 'anything as string', 'quiet': False, '_self': <module 'pymol.cmd' from '/home/peu/Desktop/pymol-open-source/modules/pymol/cmd.py'>}

If you need more examples, here a non exhaustive list of examples [1]. Inspect cmd.do() calls because they contain code exactly as they would be written in command line.

Details

It improves on extend, the consolidated exposing mechanism. It works by parsing the arguments given at command-line by users, enforcing correct types at runtime ensuring typing strictness and so easing the development. It is also advantageous for developers consuming the exposed function/command directly by the API as types can also be enforced statically by MyPy.

Zero-overhead with direct access

Before really parse arguments, it is expected this feature to introspect quickly if it was called by the PyMOL parser and can benefit from further parsing refinement or if it was called by another function and this feature is not needed. However this introspection behavior consumes the Python traceback API which can be a slowness factor. Because of this, we provide direct access for developers to the function with zero overhead by the .func attribute.

# works the same for developers
>>> nice_tool(10, [0.1, 2.3, 4.5], 'Have a nice tool', this_list=[True, False, True, False])
>>> nice_tool.func(10, [0.1, 2.3, 4.5], 'Have a nice tool', this_list=[True, False, True, False])

Here a quick benchmark (remove the print statement before trying it).

from timeit import timeit
>>> timeit("nice_tool(10, [0.1, 2.3, 4.5], 'Have a nice tool', this_list=[True, False, True, False])")
6.0971875859977445
>>> timeit("nice_tool.func(10, [0.1, 2.3, 4.5], 'Have a nice tool', this_list=[True, False, True, False])")
0.12023865499941166