New Command

IN ACTIVE DEVELOPMENT

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

In a brief

If you need more examples, here a non exhaustive list of examples: [1]

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 = 1,  # 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'>}

Details

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