Difference between revisions of "Extend"

From PyMOLWiki
Jump to: navigation, search
(auto_arg)
(rework page)
Line 1: Line 1:
[[Extend]] is an API-only function which binds a new external function as a command into the PyMOL scripting language. In other words, when you write a function and want PyMOL to recognize the new command, you '''extend''' the command into PyMOL. Once extended, the function name is recognized like other function names (example below).  Typically, '''extend''' is the last line of a PyMOL script.
+
<div style="padding: 5px 0 5px 20px; font-style: italic">
 +
This page is about an API function. For the selection operator with the same name, see [[extend (selection operator)]].
 +
</div>
 +
 
 +
[[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 ==
 +
 
 +
<source lang="python">
 +
pymol.cmd.extend(string name, function function)
 +
</source>
 +
 
 +
Simplified (since PyMOL 1.6), takes the function name as command name and can be used as a function [https://en.wikipedia.org/wiki/Python_syntax_and_semantics#Decorators decorator]:
  
===PYMOL API===
 
 
<source lang="python">
 
<source lang="python">
cmd.extend(string name,function function)
+
pymol.cmd.extend(function function)
 
</source>
 
</source>
  
===PYTHON EXAMPLE===
+
== Simple Example ==
 +
 
 +
Put the following in a Python script (e.g. file.py) and "run" the script (e.g. with "File > Run...").
 +
 
 
<source lang="python">
 
<source lang="python">
def foo(moo=2): print moo
+
from pymol import cmd
cmd.extend('foo',foo)
+
 
 +
def foo(moo=2):
 +
    print moo
 +
 
 +
cmd.extend('foo', foo)
 
</source>
 
</source>
  
The following would now work within PyMOL:
+
Or with decorator syntax (since PyMOL 1.6):
 +
 
 +
<source lang="python">
 +
from pymol import cmd
 +
 
 +
@cmd.extend
 +
def foo(moo=2):
 +
    print moo
 +
</source>
 +
 
 +
The following would now work within PyMOL's command line:
 +
 
 
<source lang="python">
 
<source lang="python">
 
PyMOL>foo
 
PyMOL>foo
Line 21: Line 56:
 
5
 
5
 
PyMOL>foo ?
 
PyMOL>foo ?
 
 
Usage: foo [ moo ]
 
Usage: foo [ moo ]
 
</source>
 
</source>
  
===NOTES===
+
== Advanced Example ==
For security reasons, new PyMOL commands created using "extend" are not saved or restored in sessions.
+
 
 +
This example provides a command help, does proper type conversion of arguments and would work with '''pymol2'''.
 +
 
 +
<source lang="python">
 +
from pymol import cmd
 +
 
 +
@cmd.extend
 +
def adjust_vdw(selection="all", factor=0.5, quiet=1, _self=cmd):
 +
    """
 +
DESCRIPTION
  
You may want to set [[auto_arg]] to enable auto-completion for your command's arguments.
+
    The "adjust_vdw" command alters all vdw radii in the given selection
 +
    by the given scale factor.
 +
    """
 +
    factor = float(factor)
 +
    quiet = int(quiet)
  
===SEE ALSO===
+
    n = _self.alter(selection, "vdw = vdw * %f" % (factor))
*[[Alias]]
+
 
*[[Api]]
+
    if n > 0:
*[[auto_arg]]
+
      _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)
 +
</source>
 +
 
 +
== Notes and recommendations ==
  
[[Category:Scripting]]
+
* So far reasonable, provide default values for arguments (like '''selection="all"''').
[[Category:Commands|Extend]]
+
* Provide a [https://en.wikipedia.org/wiki/Docstring#Python 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 ==
  
<hr>
+
*[[alias]]
=== "extend" used in selections ===
+
*[[Set_Key|set_key]]
"extend" can also be used in selection statements to grow a selection based on covalent bonds.  This behavior is illustrated on residue 64 of PDB file 1KAO where we initially select one atom and then "extend" that selection by one and three covalent bonds.
+
*[[api]]
 +
*[[auto_arg]]
  
<table border="1">
+
[[Category:Scripting]]
<tr>
 
<td>[[Image:Extend0.png|250px]]</td>
 
<td>[[Image:Extend1.png|250px]]</td>
 
<td>[[Image:Extend3.png|250px]]</td>
 
</tr>
 
<tr>
 
<td>select (resi 64 and n. cz)</td>
 
<td>select (resi 64 and n. cz) extend 1</td>
 
<td>select (resi 64 and n. cz) extend 3</td>
 
</tr>
 
</table>
 
<hr>
 

Revision as of 14:10, 5 August 2015

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