Difference between revisions of "Extend"

From PyMOLWiki
Jump to: navigation, search
m (Python 3)
 
(7 intermediate revisions by 5 users not shown)
Line 1: Line 1:
===DESCRIPTION===
+
<div style="padding: 5px 0 5px 20px; font-style: italic">
'''extend''' is an API-only function which binds a new external function as a command into the PyMOL scripting language.
+
This page is about an API function. For the selection operator with the same name, see [[extend (selection operator)]].
 +
</div>
  
===PYMOL API===
+
[[Extend]] is an API-only function which binds a user defined function as a command into the PyMOL scripting language.
cmd.extend(string name,function function)
 
  
===PYTHON EXAMPLE===
+
== Details ==
def foo(moo=2): print moo
 
cmd.extend('foo',foo)
 
  
The following would now work within PyMOL:
+
* 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).
PyMOL>foo
+
* 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.
2
+
* 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>foo 3
 
3
 
PyMOL>foo moo=5
 
5
 
PyMOL>foo ?
 
  
 +
== 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]:
 +
 +
<source lang="python">
 +
pymol.cmd.extend(function function)
 +
</source>
 +
 +
== 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">
 +
from pymol import cmd
 +
 +
def foo(moo=2):
 +
    print(moo)
 +
 +
cmd.extend('foo', foo)
 +
</source>
 +
 +
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">
 +
PyMOL>foo
 +
2
 +
PyMOL>foo 3
 +
3
 +
PyMOL>foo moo=5
 +
5
 +
PyMOL>foo ?
 
Usage: foo [ moo ]
 
Usage: foo [ moo ]
 +
</source>
 +
 +
== Advanced Example ==
 +
 +
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
 +
 +
    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))
 +
</source>
 +
 +
== Notes and recommendations ==
 +
 +
* So far reasonable, provide default values for arguments (like '''selection="all"''').
 +
* 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).
  
===NOTES===
+
== See Also ==
For security reasons, new PyMOL commands created using "extend" are not saved or restored in sessions.
 
  
===SEE ALSO===
+
*[[alias]]
[[Cmd alias|alias]], [[Cmd api|api]]
+
*[[Set_Key|set_key]]
 +
*[[api]]
 +
*[[auto_arg]]
  
[[Category:Commands|extend]]
+
[[Category:Scripting]]

Latest revision as of 02:03, 29 June 2018

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