Improvements on the `@cmd.declare_command` API #448

pslacerda · 2025-04-12T07:51:07Z

A write a bunch of tests and did my best to achieve best ergonomic API.

Only optional (None) data is still failing in some cases.

JarrettSJohnson · 2025-05-12T23:09:14Z

I'll ask if we can maintain our pattern of keeping tests in testing (rather than adding tests in module).

pslacerda · 2025-05-13T00:08:45Z

Sorry, it was my bad. I'll tackle this in a few days.

pslacerda · 2025-05-13T15:48:34Z

@JarrettSJohnson I'd like to ask, should I proceed and refactor existing commands to adhere the declare_command API?

pslacerda · 2025-05-13T15:52:07Z

The first step is to refactor the help command to also support this API.

JarrettSJohnson · 2025-05-13T16:24:11Z

@JarrettSJohnson I'd like to ask, should I proceed and refactor existing commands to adhere the declare_command API?

We can address that in a separate PR, if possible. Also I think some things were accidentally deleted, perhaps during the merging process? (e.g. testDeleteStates)

pslacerda · 2025-05-13T21:43:00Z

The tip of branch were based on an old commit. It took me several hours to finish this git chore task.

JarrettSJohnson

Generally looks fine to me, I was under the impression from the original PR that this would just be for extended, custom functions rather than native ones. I'm a little hesitant to change current commands just yet. I still need to play around with this first to ensure no functional changes.

JarrettSJohnson · 2025-05-13T22:41:42Z

testing/tests/api/helping.py

@@ -1,50 +0,0 @@
-import sys


Was this file intended to be removed here?

Yes. Is it ok?

Please keep for now since we still have code that uses this pattern.

modules/pymol/commanding.py

pslacerda · 2025-05-14T05:49:48Z

I still need to play around with this first to ensure no functional changes.

Me too. Except for the help command which I want to adjust soon, I'll take a time before any progress.

- Bio.pairwise2 has been deprecated -> Use Bio.Align.PairwiseAligner instead - SeqRecord constructor: Using a string as the sequence is deprecated -> Convert to Seq The changes are based on https://github.com/speleo3/pymol-psico/blob/ae2b92c262bc/psico/seqalign.py

pslacerda · 2025-07-15T20:14:21Z

If I remove the docs-on-comment feature will this be merged faster?

JarrettSJohnson · 2025-07-15T20:22:13Z

Apologies. Give me until the weekend, and I'll come back to this review. My involvement with incentive and open-source comes in waves, and I'm still pretty deep in 3.2/3.3 work.

pslacerda · 2025-07-21T20:31:55Z

I think this is important to get merged before 3.2 because otherwise will have a delay starting in the current incomplete feature awaiting 3.3.

modules/pymol/commanding.py

JarrettSJohnson · 2025-07-22T05:13:54Z

testing/tests/api/helping.py

@@ -1,50 +0,0 @@
-import sys


Please keep for now since we still have code that uses this pattern.

modules/pymol/commanding.py

JarrettSJohnson · 2025-07-22T05:33:30Z

modules/pymol/commanding.py

+                        break
+                    i += 1
+                else:
+                    i -= 3


I don't think I follow this line

Me neither, I just placed it here because was needed. I'd need to debug to remember exactly, but seems to me that it's related to rewind the cursor i when no doc is found.

JarrettSJohnson · 2025-07-22T05:34:56Z

modules/pymol/commanding.py

+
+        raise pymol.CmdException(f"Unsupported argument type {type}")
+
+    def parse_documentation(func):


I think this function probably needs its own unit test as well. The API to me is not inherently clear.

It is tested integrated with declare_command on test_declare_command_arg_docs.

I understand, but something like this probably deserves its own test too if possible. I'll make it optional, but I will likely add it later.

pslacerda · 2025-07-23T02:23:35Z

Give me some days and I'll fix according to your review.

As nobody is using this yet, including me, may cmd.declare_command be renamed to cmd.new or cmd.new_command?

JarrettSJohnson · 2025-07-23T06:58:16Z

Sure. new_command is fine. We already make use of cmd._new privately and it would be good for us not to be confused with the two.

pslacerda1 · 2025-09-13T16:55:13Z

Hi @JarrettSJohnson!

I lost the access to my old Github account. I'm using this new one for now. However I couldn't get open-source PyMOL working on pip editable (link) mode (pip install -e .). Can you show me how to get pytest working so I can further work on this feature?

JarrettSJohnson · 2025-09-13T21:45:00Z

Does normal pip install . work for you?

Also, you should just be able to run a test like:

python testing/testing.py --run testing/tests/api/test_viewing.py

But if you run all tests, unittest and pytest should all just run automatically.

pslacerda1 · 2025-09-14T03:54:11Z

I'm on a recent Debian and installed pyqt6-dev via default repositories. No way to get PyMOL working with Qt.

Qt not available (pymol.Qt), using GLUT/Tk interface
Traceback (most recent call last):
  File "/home/peu/Desktop/pymol-open-source/venv/bin/pymol", line 8, in <module>
    sys.exit(launch())
             ^^^^^^^^
  File "/home/peu/Desktop/pymol-open-source/venv/lib/python3.11/site-packages/pymol/__init__.py", line 429, in launch
    _cmd.runpymol(None, block_input_hook)
NotImplementedError: compile with --glu

pslacerda1 · 2025-09-14T04:38:54Z

I'm on a recent Debian install with default apt repositories. How to fix it?

PyMOL(TM) Molecular Graphics System, Version 3.2.0a.
 Copyright (c) Schrodinger, LLC.
 All Rights Reserved.

    Created by Warren L. DeLano, Ph.D.

    PyMOL is user-supported open-source software.  Although some versions
    are freely available, PyMOL is not in the public domain.

    If PyMOL is helpful in your work or study, then please volunteer
    support for our ongoing efforts to create open and affordable scientific
    software by purchasing a PyMOL Maintenance and/or Support subscription.

    More information can be found at "http://www.pymol.org".

    Enter "help" for a list of commands.
    Enter "help <command-name>" for information on a specific command.

 Hit ESC anytime to toggle between text and graphics.

 Detected OpenGL version 4.6. Shaders available.
 Detected GLSL version 4.60.
 OpenGL graphics engine:
  GL_VENDOR:   Intel
  GL_RENDERER: Mesa Intel(R) Xe Graphics (TGL GT2)
  GL_VERSION:  4.6 (Compatibility Profile) Mesa 22.3.6
 Detected 8 CPU cores.  Enabled multithreaded rendering.
PyMOL>set fetch_path, /home/peu/.local/share/PyMOL/fetch-path
 Setting: fetch_path set to /home/peu/.local/share/PyMOL/fetch-path.

GL_ERROR : 0x0506 GenericBuffer::genBuffer failed

GL_ERROR : 0x0502 GLTextureBuffer::texture_subdata_2D failed
PyMOL>ray 628, 463, async=1
 Ray: render time: 0.00 sec. = 1273896.4 frames/hour (0.00 sec. accum.).
GL_ERROR : 0x0502 GenericBuffer::genBuffer failed

PyMOL>draw 628, 463
GL_ERROR : 0x0502 GenericBuffer::genBuffer failed

GL_ERROR : 0x0506 GenericBuffer::genBuffer failed

GL_ERROR : 0x0502 GenericBuffer::genBuffer failed

GL_ERROR : 0x0506 GenericBuffer::genBuffer failed

GL_ERROR : 0x0506 GenericBuffer::genBuffer failed

GL_ERROR : 0x0506 GenericBuffer::genBuffer failed

PyMOL>wizard appearance
GL_ERROR : 0x0506 GLTextureBuffer::texture_subdata_2D failed
QThreadStorage: entry 3 destroyed before end of thread 0x1ce23f90
QThreadStorage: entry 1 destroyed before end of thread 0x1ce23f90
QThreadStorage: entry 0 destroyed before end of thread 0x1ce23f90

ye11owSub · 2025-09-14T09:53:42Z

Hi @pslacerda1!

I don't have a Debian machine available at the moment, but maybe one of these solutions will help you.
You can try installing pyqt as a Python library using the command pip install pyqt5 or you can install the entire project by running the command pip install '.[dev]'(this will automatically install pyside6 as one of the dependencies)

pslacerda1 · 2025-10-07T18:24:22Z

Hi, sorry for the slow response. I still can't fully start PyMOL open-source because I'm not seeing anything on the "canvas".

GL_ERROR : 0x0506 GenericBuffer::genBuffer failed
GL_ERROR : 0x0502 GLTextureBuffer::texture_subdata_2D failed
PyMOL>ray 628, 463, async=1
 Ray: render time: 0.00 sec. = 2007911.5 frames/hour (0.00 sec. accum.).
GL_ERROR : 0x0502 GenericBuffer::genBuffer failed

JarrettSJohnson · 2025-10-07T18:51:11Z

Not sure about this, unfortunately. Does the latest Incentive version also show the same issue? Also does set use_shaders, 0 show any difference?

pslacerda1 · 2025-10-07T19:36:58Z

Incentive PyMOL and pymol-open-source starts like this same. However incentive continue and works while open-source fails.

 Detected OpenGL version 4.6. Shaders available.
 Detected GLSL version 4.60.
 OpenGL graphics engine:
  GL_VENDOR:   Intel
  GL_RENDERER: Mesa Intel(R) Xe Graphics (TGL GT2)
  GL_VERSION:  4.6 (Compatibility Profile) Mesa 22.3.6
 Detected 8 CPU cores.  Enabled multithreaded rendering.

JarrettSJohnson · 2025-10-07T20:57:39Z

No changes with the use_shaders setting, and it's up to date with master? I recently pulled in some changes to keep the graphics changes similar to Incentive.

pslacerda1 · 2025-10-07T22:13:49Z

Yes, I'm synced to master.

pslacerda1 · 2025-10-09T01:58:27Z

Please, provide me the hashes of your commits?

What I tried? I checkout and tried to build & run master and tag v3.1.0. Master starts without anything related to GL, v3.1.0 pop up on the screen and closes instantaneously.

pslacerda1 · 2025-10-09T03:27:06Z

Good and bad news: I was attempting to use the wrong Qt version. The correct is Qt5 for PyMOL 3.1 and Qt6 for PyMOL 3.2. The bad one is that I couldn't run all pytests from tests/testing/api anymore.

Copilot

Pull Request Overview

This PR introduces improvements to the @cmd.declare_command API to provide better ergonomics for command declaration and type casting. The changes focus on enhancing the command declaration system with more robust type handling and documentation parsing capabilities.

Replaced the previous test file for API helping functionality with comprehensive command declaration tests
Enhanced the declare_command decorator with improved type casting and argument handling
Added support for complex types including Optional, Union, Tuple, Enum, and generic types

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
testing/tests/api/helping.py	Completely removed the help API test file
testing/tests/api/commanding.py	Added extensive tests for the new command declaration API with various type scenarios
modules/pymol/commanding.py	Implemented enhanced type casting system and argument documentation parsing for command declarations

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-10T22:35:02Z

testing/tests/api/commanding.py

+
+    @cmd.declare_command
+    def func(a: Optional[int] = None):
+        assert a is 10


Use == for value comparison instead of is. The is operator checks for object identity, not equality, and may not work reliably for integers.

Suggested change

assert a is 10

assert a == 10

Copilot · 2025-10-10T22:35:02Z

modules/pymol/commanding.py


-    def _parse_list_int(value):
-        return list(map(int, shlex.split(value)))
+        elif isinstance(type, Enum):


This condition will never be true. type is a type annotation, not an instance of Enum. Use inspect.isclass(type) and issubclass(type, Enum) to check if the type is an Enum class.

Copilot · 2025-10-10T22:35:03Z

modules/pymol/commanding.py

+            else:
+                raise pymol.CmdException(f"Invalid value for enum {type.__name__}: {value}")
+
+        elif isinstance(type, builtins.type):


This condition is too broad and may incorrectly handle type annotations. Consider using more specific type checking logic or inspect.isclass() for better type validation.

Suggested change

elif isinstance(type, builtins.type):

elif inspect.isclass(type):

Copilot · 2025-10-10T22:35:03Z

modules/pymol/commanding.py

+        while True:
+            i += 1
+            if tokens[i].string == "def":
+                while tokens[i].string == "(":


This will cause an infinite loop if the opening parenthesis is found, as the condition never changes. The logic should find the opening parenthesis and then break or continue processing.

Suggested change

while tokens[i].string == "(":

if tokens[i].string == "(":

Copilot · 2025-10-10T22:35:03Z

modules/pymol/commanding.py

+            if tokens[i].type == tokenize.NAME and tokens[i+1].string == ":":
+                name = tokens[i].string
+                name_line = tokens[i].line
+                i += 1
+                while not (tokens[i].type == tokenize.NAME and tokens[i+1].string == ":"):


This loop may cause an IndexError when accessing tokens[i+1] if i reaches the end of the tokens list. Add bounds checking before accessing tokens[i+1].

Suggested change

if tokens[i].type == tokenize.NAME and tokens[i+1].string == ":":

name = tokens[i].string

name_line = tokens[i].line

i += 1

while not (tokens[i].type == tokenize.NAME and tokens[i+1].string == ":"):

if tokens[i].type == tokenize.NAME and (i+1 < len(tokens)) and tokens[i+1].string == ":":

name = tokens[i].string

name_line = tokens[i].line

i += 1

while not (tokens[i].type == tokenize.NAME and (i+1 < len(tokens)) and tokens[i+1].string == ":"):

Copilot · 2025-10-10T22:35:03Z

modules/pymol/commanding.py

-        _self.keyword[name] = [inner, 0, 0, ",", parsing.STRICT]
-        _self.kwhash.append(name)
-        _self.help_sc.append(name)
+        _self.keyword[name] = [inner, 0,0,',',parsing.STRICT]


[nitpick] Inconsistent spacing around commas. Should be [inner, 0, 0, ',', parsing.STRICT] to match Python style conventions.

Suggested change

_self.keyword[name] = [inner, 0,0,',',parsing.STRICT]

_self.keyword[name] = [inner, 0, 0, ',', parsing.STRICT]

pslacerda mentioned this pull request Apr 12, 2025

Renewed plugins #347

Open

pslacerda force-pushed the declare_command branch 2 times, most recently from 80eb0ce to 7c9f7ff Compare May 13, 2025 15:41

Refactor @cmd.declare_command

095e961

pslacerda force-pushed the declare_command branch from 7c9f7ff to 095e961 Compare May 13, 2025 21:23

JarrettSJohnson reviewed May 13, 2025

View reviewed changes

pslacerda1 and others added 9 commits May 31, 2025 21:18

Fix mixed string formatting

d0f8406

Fix quient default parameter

40d5053

Fix declare_command on Windows (schrodinger#459)

9fc0304

Fixed build on FreeBSD (schrodinger#461)

3140e28

Sorry for the messy commits

3aa351b

Merge branch 'master' into declare_command

a78deb4

Fix some bugs

3612302

Add support for Enum types in the declare_command

b2493c7

pslacerda mentioned this pull request Jun 23, 2025

Plugins needing refactor Pymol-Scripts/Pymol-script-repo#147

Open

JarrettSJohnson requested changes Jul 22, 2025

View reviewed changes

pslacerda1 added 2 commits July 22, 2025 11:35

Documents declare_command helpers

ab4c87e

Prefer f-strings

22ba8f8

pslacerda1 mentioned this pull request Oct 9, 2025

Declaring new commands #470

Merged

JarrettSJohnson requested a review from Copilot October 10, 2025 22:33

Copilot AI reviewed Oct 10, 2025

View reviewed changes


		raise pymol.CmdException(f"Unsupported argument type {type}")

		def parse_documentation(func):

	elif isinstance(type, builtins.type):
	elif inspect.isclass(type):

	_self.keyword[name] = [inner, 0,0,',',parsing.STRICT]
	_self.keyword[name] = [inner, 0, 0, ',', parsing.STRICT]

Improvements on the @cmd.declare_command API #448

Are you sure you want to change the base?

Improvements on the @cmd.declare_command API #448

Uh oh!

Conversation

pslacerda commented Apr 12, 2025

Uh oh!

JarrettSJohnson commented May 12, 2025

Uh oh!

pslacerda commented May 13, 2025

Uh oh!

pslacerda commented May 13, 2025

Uh oh!

pslacerda commented May 13, 2025

Uh oh!

JarrettSJohnson commented May 13, 2025

Uh oh!

pslacerda commented May 13, 2025

Uh oh!

JarrettSJohnson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pslacerda commented May 14, 2025

Uh oh!

pslacerda commented Jul 15, 2025

Uh oh!

JarrettSJohnson commented Jul 15, 2025

Uh oh!

pslacerda commented Jul 21, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pslacerda commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JarrettSJohnson commented Jul 23, 2025

Uh oh!

pslacerda1 commented Sep 13, 2025

Uh oh!

JarrettSJohnson commented Sep 13, 2025

Uh oh!

pslacerda1 commented Sep 14, 2025

Uh oh!

pslacerda1 commented Sep 14, 2025

Uh oh!

ye11owSub commented Sep 14, 2025

Uh oh!

pslacerda1 commented Oct 7, 2025

Uh oh!

JarrettSJohnson commented Oct 7, 2025

Uh oh!

pslacerda1 commented Oct 7, 2025

Uh oh!

JarrettSJohnson commented Oct 7, 2025

Uh oh!

pslacerda1 commented Oct 7, 2025

Uh oh!

pslacerda1 commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Improvements on the `@cmd.declare_command` API #448

Improvements on the `@cmd.declare_command` API #448

pslacerda commented Jul 23, 2025 •

edited

Loading

pslacerda1 commented Oct 9, 2025 •

edited

Loading