Extend

This page is about an API function. For the selection operator with the same name, see extend (selection operator).

Extend is an API-only function which binds a user defined function as a command into the PyMOL scripting language.

Details

• All command arguments are passed as strings to the Python function. This may require type conversion before those arguments can be used by the function, for example for numbers (int, float).
• If the function has a quiet argument, then PyMOL will pass quiet=0 to the command. Most PyMOL core commands have a default quiet=1 argument and have no (or little) output when used in a Python script, but would print a more verbose feedback when invoked as a command.
• If the function has a _self argument, then PyMOL will assign the global cmd module to _self, or if using the pymol2 module, an instance of pymol2.cmd2.Cmd. This wrapper allows running multiple PyMOL instances in the same process.

PyMOL API

pymol.cmd.extend(string name, function function)

Simplified (since PyMOL 1.6), takes the function name as command name and can be used as a function decorator:

pymol.cmd.extend(function function)

Simple Example

Put the following in a Python script (e.g. file.py) and "run" the script (e.g. with "File > Run...").

from pymol import cmd

def foo(moo=2):
    print(moo)

cmd.extend('foo', foo)

Or with decorator syntax (since PyMOL 1.6):

from pymol import cmd

@cmd.extend
def foo(moo=2):
    print(moo)

The following would now work within PyMOL's command line:

PyMOL>foo
2
PyMOL>foo 3
3
PyMOL>foo moo=5
5
PyMOL>foo ?
Usage: foo [ moo ]

Advanced Example

This example provides a command help, does proper type conversion of arguments and would work with pymol2.

from pymol import cmd

@cmd.extend
def adjust_vdw(selection="all", factor=0.5, quiet=1, _self=cmd):
    """
DESCRIPTION

    The "adjust_vdw" command alters all vdw radii in the given selection
    by the given scale factor.
    """
    factor = float(factor)
    quiet = int(quiet)

    n = _self.alter(selection, "vdw = vdw * %f" % (factor))

    if n > 0:
      _self.rebuild()

    if not quiet:
        if n == 0:
            print(" No atoms in selection")
        else:
            print(" Updated VDW radii of %d atoms by factor %.2f" % (n, factor))

Notes and recommendations

• So far reasonable, provide default values for arguments (like selection="all").
• Provide a docstring in the same format like all other PyMOL core commands (with DESCRIPTION, USAGE, etc.), that will make calling "help yourcommand" a familiar experience for a user.
• Take advantage of PyMOL's selection language, a command which takes a selection argument will feel more familiar to a user than a command which takes for example object, chain and resid arguments.
• Pass boolean values as 0/1 instead of named values like true, on, yes / false, ..., that will be consistent with PyMOL's core commands.
• You may want to set auto_arg to enable auto-completion for your command's arguments.
• For security reasons, new PyMOL commands created using "extend" are not saved or restored in sessions (PSE files).

See Also

• alias
• set_key
• api
• auto_arg