Add new pystub proxy support #5

DevTGHa · 2026-01-06T10:16:56Z

Add pystub proxy support

Summary

This PR introduces a Python proxy object for the stub file d3.pyi, removing the need for clients to hide the d3 module behind TYPE_CHECKING.

Previously, this limitation made it hard to reference the d3 plugin type as a function return type.
The new proxy resolves that issue and improves the overall typing experience.

Old

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from designer_plugin.pystub.d3 import *

def my_fn() -> "Screen2":

New

from designer_plugin.pystub import *

def my_fn() -> Screen2:

In addition, the raw API interface names have been updated to align with the existing naming conventions. While it's to deprecate the old APIs, the previous release went out shortly before Christmas, so I just removed instead, keeping the surface area clean and consistent.

Changes

Renamed d3_api_plugin to d3_api_execute.
Renamed d3_api_aplugin to d3_api_aexecute.
Updated documentation to reflect pystub proxy support.

Summary by CodeRabbit

Changed
- Renamed two public API functions (updated public surface to new names).
Documentation
- Clarified that the pystub module provides IDE type hints only; runtime implementations come from Designer.
- Updated README examples and import patterns for clearer guidance.
Chores
- Bumped project version to 1.3.0 and added a changelog entry.
Tests
- Updated tests to align with the API renames.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2026-01-06T10:17:07Z

Walkthrough

Renames two public API functions (d3_api_plugin → d3_api_execute, d3_api_aplugin → d3_api_aexecute), updates all references and tests, bumps version to 1.3.0, and updates README examples to import designer_plugin.pystub directly while noting stub runtime limitations.

Changes

Cohort / File(s)	Summary
Version & Changelog `pyproject.toml`, `CHANGELOG.md`	Bumped `project.version` to `1.3.0`; added changelog entry documenting the two public symbol renames and `pystub` proxy support.
API Function Definitions `src/designer_plugin/api.py`	Renamed public sync function `d3_api_plugin` → `d3_api_execute` and async function `d3_api_aplugin` → `d3_api_aexecute`; signatures and behavior unchanged.
SDK Clients & Session `src/designer_plugin/d3sdk/client.py`, `src/designer_plugin/d3sdk/session.py`	Updated imports and calls to use `d3_api_execute` / `d3_api_aexecute` instead of the old names; no other logic changes.
Tests `tests/test_client.py`	Updated test patches/mocks to target `d3_api_execute` (formerly `d3_api_plugin`); test flows and assertions unchanged.
Documentation / Examples `README.md`	Replaced TYPE_CHECKING-guarded imports with `from designer_plugin.pystub import *` in examples; added note that `pystub` supplies type hints only, not runtime implementations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 I hopped through names both old and new,
Swapped d3_api_plugin for one called true,
Async ears perked, aexecute in sight,
Pystub lends hints but not the runtime light.
Version 1.3 — I nibble with delight.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add new pystub proxy support' refers to a real feature (pystub proxy mentioned in README changes), but the PR's primary changes are API function renames (d3_api_plugin→d3_api_execute, d3_api_aplugin→d3_api_aexecute). The pystub proxy support is secondary documentation/example updates.
Docstring Coverage	✅ Passed	Docstring coverage is 86.67% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between a4b05ba and c022a39.

📒 Files selected for processing (1)

README.md

🚧 Files skipped from review as they are similar to previous changes (1)

README.md

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

src/designer_plugin/d3sdk/client.py (1)
78-98: Update outdated API names in docstring.

The docstring still references the old API names d3_api_plugin and d3_api_aplugin on line 88. These should be updated to d3_api_execute and d3_api_aexecute.
🔎 Proposed fix
-    5. Sends it to Designer via d3_api_plugin or d3_api_aplugin
+    5. Sends it to Designer via d3_api_execute or d3_api_aexecute
src/designer_plugin/api.py (2)

222-269: Fix test mocks and comments to use renamed function.

The function was renamed from d3_api_plugin to d3_api_execute, but tests in tests/test_client.py still reference the old name in 6 mock patches (lines 74, 117, 127, 137, 147, 165). These patches will fail because they're attempting to mock a non-existent function. Additionally, a comment in src/designer_plugin/d3sdk/client.py:88 references the old function name and needs updating.

Update all test patches from patch('designer_plugin.d3sdk.client.d3_api_plugin', ...) to patch('designer_plugin.d3sdk.client.d3_api_execute', ...) and update the source code comment.

128-174: Update docstring in src/designer_plugin/d3sdk/client.py to reflect renamed function.

While the rename from d3_api_aplugin to d3_api_aexecute has been completed successfully with all usages and imports updated, the docstring at line 88 in client.py still references the old function names: "Sends it to Designer via d3_api_plugin or d3_api_aplugin". This should be updated to reference the current function names (d3_api_execute for sync and d3_api_aexecute for async).

🧹 Nitpick comments (1)

CHANGELOG.md (1)
8-13: Changelog entry is well-formatted and documents key changes.

The 1.3.0 entry follows the Keep a Changelog format correctly and captures the API renames and pystub documentation update. However, consider clarifying that these are breaking changes (old API names are removed, not available alongside new names) to help users understand migration urgency.

Consider rephrasing the API rename entries to explicitly indicate removal for clarity:
🔎 Suggested enhancement for breaking change clarity
 ### Changed
-- `d3_api_plugin` has been renamed to `d3_api_execute`.
-- `d3_api_aplugin` has been renamed to `d3_api_aexecute`.
+- **BREAKING**: `d3_api_plugin` has been removed; use `d3_api_execute` instead.
+- **BREAKING**: `d3_api_aplugin` has been removed; use `d3_api_aexecute` instead.
 - Updated documentation to reflect `pystub` proxy support.
This makes it explicit that these are not backward-compatible changes and require code updates from users of the old API names.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 3f33f62 and edf2221.

📒 Files selected for processing (6)

CHANGELOG.md
README.md
pyproject.toml
src/designer_plugin/api.py
src/designer_plugin/d3sdk/client.py
src/designer_plugin/d3sdk/session.py

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: DevTGHa
Repo: disguise-one/python-plugin PR: 4
File: README.md:97-97
Timestamp: 2025-12-01T16:07:14.243Z
Learning: The `designer-plugin-pystub` package is a separate PyPI package (not part of the designer-plugin repository) that provides type stubs for Designer's Python API. It is installed separately via `pip install designer-plugin-pystub` and imported under `TYPE_CHECKING` blocks for IDE autocomplete.

📚 Learning: 2025-12-01T16:07:14.243Z

Learnt from: DevTGHa
Repo: disguise-one/python-plugin PR: 4
File: README.md:97-97
Timestamp: 2025-12-01T16:07:14.243Z
Learning: The `designer-plugin-pystub` package is a separate PyPI package (not part of the designer-plugin repository) that provides type stubs for Designer's Python API. It is installed separately via `pip install designer-plugin-pystub` and imported under `TYPE_CHECKING` blocks for IDE autocomplete.

Applied to files:

README.md
pyproject.toml

🧬 Code graph analysis (1)

src/designer_plugin/d3sdk/session.py (2)

src/designer_plugin/api.py (3)

d3_api_aexecute (128-173)

d3_api_arequest (97-123)

d3_api_execute (222-269)

src/designer_plugin/d3sdk/function.py (2)

payload (207-223)

payload (350-368)

🔇 Additional comments (8)

pyproject.toml (1)

7-7: Version bump aligns with feature changes and breaking API removals.

The minor version bump to 1.3.0 is appropriate for feature additions (pystub proxy support) and breaking API changes (d3_api_plugin → d3_api_execute, d3_api_aplugin → d3_api_aexecute). Since these are breaking changes, confirm that users are notified in release notes and the changelog clearly indicates this is a breaking release.

README.md (1)

103-103: Client and Functional API examples correctly updated with new import.

Both examples consistently use the new simplified import pattern from designer_plugin.pystub import *, maintaining consistency with the documented pattern in the "Stub file" section.

Also applies to: 187-187

src/designer_plugin/d3sdk/session.py (3)

10-18: LGTM: Imports updated correctly.

The imports correctly reflect the renamed API functions (d3_api_aexecute and d3_api_execute).

120-120: LGTM: Synchronous execute call updated.

The synchronous session correctly calls the renamed d3_api_execute function.

273-273: LGTM: Asynchronous execute call updated.

The asynchronous session correctly calls the renamed d3_api_aexecute function.

src/designer_plugin/d3sdk/client.py (3)

15-20: LGTM: Imports updated correctly.

The imports correctly reflect the renamed API functions (d3_api_aexecute and d3_api_execute).

115-118: LGTM: Asynchronous wrapper updated correctly.

The async wrapper correctly calls the renamed d3_api_aexecute function.

133-136: LGTM: Synchronous wrapper updated correctly.

The sync wrapper correctly calls the renamed d3_api_execute function.

README.md

coderabbitai

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/designer_plugin/d3sdk/client.py (1)
78-98: Update the docstring to reference the new API names.

The docstring on line 88 still references the old API names. Update it to reflect the renamed functions.
🔎 Suggested fix
     3. Builds a script string in the form: "return plugin.{method_name}({args})"
     4. Creates a PluginPayload with the script and module information
-    5. Sends it to Designer via d3_api_plugin or d3_api_aplugin
+    5. Sends it to Designer via d3_api_execute or d3_api_aexecute
     6. Returns the result from the remote execution

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between edf2221 and a4b05ba.

⛔ Files ignored due to path filters (1)

uv.lock is excluded by !**/*.lock

📒 Files selected for processing (7)

CHANGELOG.md
README.md
pyproject.toml
src/designer_plugin/api.py
src/designer_plugin/d3sdk/client.py
src/designer_plugin/d3sdk/session.py
tests/test_client.py

🚧 Files skipped from review as they are similar to previous changes (4)

README.md
CHANGELOG.md
pyproject.toml
src/designer_plugin/d3sdk/session.py

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: DevTGHa
Repo: disguise-one/python-plugin PR: 4
File: README.md:97-97
Timestamp: 2025-12-01T16:07:14.243Z
Learning: The `designer-plugin-pystub` package is a separate PyPI package (not part of the designer-plugin repository) that provides type stubs for Designer's Python API. It is installed separately via `pip install designer-plugin-pystub` and imported under `TYPE_CHECKING` blocks for IDE autocomplete.

🧬 Code graph analysis (1)

src/designer_plugin/d3sdk/client.py (2)

src/designer_plugin/api.py (3)

d3_api_aexecute (128-173)

d3_api_aregister_module (176-217)

d3_api_execute (222-269)

src/designer_plugin/models.py (1)

PluginResponse (45-89)

🔇 Additional comments (6)

tests/test_client.py (1)

74-74: LGTM! Test patches updated consistently.

All patch targets correctly updated from d3_api_plugin to d3_api_execute to align with the API rename. The test logic remains unchanged, ensuring continued validation of the updated API surface.

Also applies to: 117-117, 127-127, 137-137, 147-147, 165-165

src/designer_plugin/api.py (2)

128-173: LGTM! Clean async API rename.

Function renamed from d3_api_aplugin to d3_api_aexecute with signature and behavior preserved.

222-269: LGTM! Clean sync API rename.

Function renamed from d3_api_plugin to d3_api_execute with signature and behavior preserved.

src/designer_plugin/d3sdk/client.py (3)

16-20: LGTM! Imports updated correctly.

Import statements updated to reference the renamed API functions d3_api_aexecute and d3_api_execute.

115-118: LGTM! Async call site updated correctly.

Call updated to use the renamed d3_api_aexecute function.

133-136: LGTM! Sync call site updated correctly.

Call updated to use the renamed d3_api_execute function.

chrisnashdisguise

So the code which implements the proxy will be in the pystub repository? Should there be some dependency version change for that repo here somewhere?

README.md

Co-authored-by: Chris Nash <chris.nash@disguise.one>

DevTGHa · 2026-01-13T11:16:16Z

So the code which implements the proxy will be in the pystub repository? Should there be some dependency version change for that repo here somewhere?

The version change will be on pystub repository itself.

https://github.com/disguise-one/Designer_Plugin_pystub

I'm currently testing with test-pypi server to make sure everything is working as expected.

chrisnashdisguise · 2026-01-13T11:27:20Z

So the code which implements the proxy will be in the pystub repository? Should there be some dependency version change for that repo here somewhere?

The version change will be on pystub repository itself.

https://github.com/disguise-one/Designer_Plugin_pystub

I'm currently testing with test-pypi server to make sure everything is working as expected.

Should this repo have a dependency on the pystub repo? Even if it doesn't directly use it, we might need to enforce version compatibility in cases like this?

DevTGHa self-assigned this Jan 6, 2026

DevTGHa added the enhancement New feature or request label Jan 6, 2026

coderabbitai bot reviewed Jan 6, 2026

View reviewed changes

README.md Show resolved Hide resolved

add new pystub proxy support

a4b05ba

DevTGHa force-pushed the update_api_naming branch from edf2221 to a4b05ba Compare January 6, 2026 10:21

coderabbitai bot reviewed Jan 6, 2026

View reviewed changes

DevTGHa requested review from chrisnashdisguise and twhittock-disguise January 12, 2026 17:00

twhittock-disguise approved these changes Jan 12, 2026

View reviewed changes

chrisnashdisguise reviewed Jan 13, 2026

View reviewed changes

README.md Outdated Show resolved Hide resolved

Update README.md

c022a39

Co-authored-by: Chris Nash <chris.nash@disguise.one>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add new pystub proxy support #5

Add new pystub proxy support #5

DevTGHa commented Jan 6, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Jan 6, 2026 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Uh oh!

chrisnashdisguise left a comment

Uh oh!

Uh oh!

DevTGHa commented Jan 13, 2026

Uh oh!

chrisnashdisguise commented Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

Add new pystub proxy support #5

Are you sure you want to change the base?

Add new pystub proxy support #5

Conversation

DevTGHa commented Jan 6, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add pystub proxy support

Summary

Changes

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

chrisnashdisguise left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DevTGHa commented Jan 13, 2026

Uh oh!

chrisnashdisguise commented Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

DevTGHa commented Jan 6, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Jan 6, 2026 •

edited

Loading