[PR #51] [MERGED] docs: cover get_workflow, asset deletion, and job_id in the README #60

New issue

Closed

opened 2026-10-31 22:01:05 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 22:01:05 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-python-sdk/pull/51
Author: @wei-hai
Created: 8/13/2026
Status: ✅ Merged
Merged: 8/13/2026
Merged by: @wei-hai

Base: main ← Head: wei/readme-v2-surface

📝 Commits (1)

b5f9925 docs: cover get_workflow, asset deletion, and job_id in the README

📊 Changes

1 file changed (+43 additions, -0 deletions)

View changed files

📝 README.md (+43 -0)

📄 Description

comfy-sdk 0.1.8 shipped three capabilities the README never mentions. A stale reference doc in a published package is worse than a missing one.

Added

Getting a job's workflow back — get_workflow() on both clients, the format discriminator (api vs save), and why this is the only way to see the graph behind a job rehydrated by id. It states plainly that submissions from this SDK always get api today, since v2 has no version-pinning fields yet.
Asset deletion — asset.delete() and client.assets.delete(id), noting it needs a proxy new enough to serve DELETE /api/v2/assets/{id}; older ones return 405.
job_id and expires_at — on assets and outputs, including that job_id is None for an uploaded asset, which has no producing job.

How it was checked

Every claim was read against the source behind it, not the changelog. The runnable parts were executed against the installed package — including confirming the pre-COMFY_BASE_URL positional call really does raise TypeError, since a sibling doc shipped examples that didn't.

The rest of the README was audited at the same time and found accurate: install requirements against pyproject.toml, the COMFY_BASE_URL and keyword-only api_key behaviour, the partner-node key distinction, client_info/User-Agent, the typed-exception list against exceptions.py's map (exact match), the two-layer architecture description, and the release commands against CI.

pytest 140 passed / 4 skipped; ruff, ruff format, mypy, and the public-repo hygiene check all clean.

Two things found but deliberately not changed

Job.cancel() and Job.refresh() have no README mention. Not stale, just absent, and the README already omits other real methods. Worth a decision on whether this doc aims at full method coverage.
AsyncOutput has no to_stream(), while Output does. That's a code asymmetry rather than a doc bug, so it stayed out of a docs-only change — but it makes the docs-site claim that the sync and async clients have "the same surface" untrue by exactly one method. Filed here so it isn't lost.

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Added guidance for asset metadata, expiration details, and deletion options.
- Documented compatibility with proxies and asynchronous asset operations.
- Added instructions for retrieving job workflows and using supported workflow formats.
- Explained how output handles identify the job that produced them.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/comfy-python-sdk/pull/51 **Author:** [@wei-hai](https://github.com/wei-hai) **Created:** 8/13/2026 **Status:** ✅ Merged **Merged:** 8/13/2026 **Merged by:** [@wei-hai](https://github.com/wei-hai) **Base:** `main` ← **Head:** `wei/readme-v2-surface` --- ### 📝 Commits (1) - [`b5f9925`](https://github.com/Comfy-Org/comfy-python-sdk/commit/b5f992527d7c1bfe755fa3c0353a60844849e610) docs: cover get_workflow, asset deletion, and job_id in the README ### 📊 Changes **1 file changed** (+43 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+43 -0) </details> ### 📄 Description `comfy-sdk` **0.1.8** shipped three capabilities the README never mentions. A stale reference doc in a published package is worse than a missing one. ## Added - **Getting a job's workflow back** — `get_workflow()` on both clients, the `format` discriminator (`api` vs `save`), and why this is the only way to see the graph behind a job rehydrated by id. It states plainly that submissions from this SDK always get `api` today, since v2 has no version-pinning fields yet. - **Asset deletion** — `asset.delete()` and `client.assets.delete(id)`, noting it needs a proxy new enough to serve `DELETE /api/v2/assets/{id}`; older ones return `405`. - **`job_id` and `expires_at`** — on assets and outputs, including that `job_id` is `None` for an uploaded asset, which has no producing job. ## How it was checked Every claim was read against the source behind it, not the changelog. The runnable parts were executed against the installed package — including confirming the pre-`COMFY_BASE_URL` positional call really does raise `TypeError`, since a sibling doc shipped examples that didn't. The rest of the README was audited at the same time and found **accurate**: install requirements against `pyproject.toml`, the `COMFY_BASE_URL` and keyword-only `api_key` behaviour, the partner-node key distinction, `client_info`/User-Agent, the typed-exception list against `exceptions.py`'s map (exact match), the two-layer architecture description, and the release commands against CI. `pytest` 140 passed / 4 skipped; ruff, ruff format, mypy, and the public-repo hygiene check all clean. ## Two things found but deliberately not changed - **`Job.cancel()` and `Job.refresh()` have no README mention.** Not stale, just absent, and the README already omits other real methods. Worth a decision on whether this doc aims at full method coverage. - **`AsyncOutput` has no `to_stream()`, while `Output` does.** That's a code asymmetry rather than a doc bug, so it stayed out of a docs-only change — but it makes the docs-site claim that the sync and async clients have "the same surface" untrue by exactly one method. Filed here so it isn't lost. 🤖 Generated with [Claude Code](https://claude.com/claude-code)  ## Summary by CodeRabbit * **Documentation** * Added guidance for asset metadata, expiration details, and deletion options. * Documented compatibility with proxies and asynchronous asset operations. * Added instructions for retrieving job workflows and using supported workflow formats. * Explained how output handles identify the job that produced them.  --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 22:01:05 +00:00