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.
- 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.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:
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 ]
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).