Skip to content

[UPSTREAM-6] feat(python): emit @nexus.doc on resources and methods as docstrings - #53

Closed
moetemp wants to merge 9 commits into
moe/up/result-record-holds-resourcefrom
moe/up/resource-docs
Closed

moetemp wants to merge 9 commits into
moe/up/result-record-holds-resourcefrom
moe/up/resource-docs

Conversation

@moetemp

@moetemp moetemp commented Oct 22, 2026 •

Copy link
Copy Markdown
Owner

What changed?

This PR uses @nexus.doc on a WIT resource and on its methods as the Python class and method docstrings. The other targets ignore it, as before.

Why?

A resource is the main surface that a caller sees, and its docs had nowhere to go.

How did you test it?

The stream-service sample has docs on stream and on two of its methods, and the Python golden shows them as docstrings.

Based on fork PR #56.

Came from fork PR #45.

@moetemp moetemp changed the title [Upstream] Emitted @nexus.doc on resources and methods as Python docstrings. [Upstream] feat: emit @nexus.doc on resources and methods as Python docstrings Oct 22, 2026
@moetemp moetemp changed the title [Upstream] feat: emit @nexus.doc on resources and methods as Python docstrings feat(python): emit @nexus.doc on resources and methods as docstrings Oct 22, 2026
@moetemp moetemp changed the title feat(python): emit @nexus.doc on resources and methods as docstrings [Upstream] feat(python): emit @nexus.doc on resources and methods as docstrings Oct 22, 2026
@moetemp moetemp changed the title [Upstream] feat(python): emit @nexus.doc on resources and methods as docstrings [UPSTREAM-6] feat(python): emit @nexus.doc on resources and methods as docstrings Oct 22, 2026
@moetemp
moetemp changed the base branch from moe/up/main to moe/up/stream-service-sample October 22, 2026 23:23
@moetemp
moetemp changed the base branch from moe/up/stream-service-sample to moe/up/ts-system-nexus-resource-return October 23, 2026 01:59
@moetemp
moetemp force-pushed the moe/up/ts-system-nexus-resource-return branch from 4ec6f17 to d9b9b23 Compare October 23, 2026 04:18
# Conflicts:
#	advanced/samples/README.md
@moetemp
moetemp changed the base branch from moe/up/ts-system-nexus-resource-return to moe/up/sample-and-system-nexus October 23, 2026 04:34
@moetemp
moetemp changed the base branch from moe/up/sample-and-system-nexus to moe/up/result-record-holds-resource October 23, 2026 06:12
moetemp added a commit to temporalio/nexgen that referenced this pull request Oct 23, 2026
)

## What changed?

This PR adds a `stream-service` sample for Python and TypeScript, with today's output. #272 adds .NET with its fix. It has a `stream` resource built from a ref, `create-stream`, append, read, describe and close, with 64-bit offsets, payloads and durations.

Its records are proto-backed, as a stream service's are. Upstream has no stream protos, so the sample has its own small proto in `descriptors/streamsample/v1/`, with checked-in bindings. The samples README has the commands that regenerate them. `build_examples` now loads every `*.bin` under `descriptors/`.

## Why?

Later fixes show their effect as a golden diff on this sample.

## How did you test it?

The goldens. A TypeScript test sends a full `ReadRecordsRequest` through the converter, so the TypeScript type file can't drift from the proto.

## What comes next

These fixes are ready, in this order. Each one adds its shape to this sample, then the fix.

- #272: adds .NET, where the `stream` field of the `Stream` class fails with CS0542, then the fix.
- [moetemp#52](moetemp#52): Check required resource fields of a response. Adds `create-stream` returning the `stream` resource.
- [moetemp#56](moetemp#56): Allow a result record to hold a resource. Adds a `create-stream-result` holder record.
- [moetemp#53](moetemp#53): Emit `@nexus.doc` on resources and methods as Python docstrings.
- [moetemp#70](moetemp#70): Convert 64-bit resource method values to `Long` for a proto request in TypeScript. Adds 64-bit method parameters. Needs #265.
- [moetemp#54](moetemp#54): Generate a Python caller per service over a transport. Turns on the client for the sample.
- [moetemp#55](moetemp#55): Add `@nexus.long-poll` to the Python caller. Marks `read-records` as a long poll.
- [moetemp#57](moetemp#57): Add Python client classes for resources with methods.
- [moetemp#71](moetemp#71): Drop the bare keyword marker from a Python signature with no parameters. Adds a `stream-writer` interface with no endpoint.
- [moetemp#60](moetemp#60): Indent the docstrings of Python caller methods. Adds a doc on a writer operation.
- [moetemp#69](moetemp#69): Import record types that an endpoint-less Python client uses in unpacked parameters. Adds `open-writer`.
- [moetemp#72](moetemp#72): Plan proto unsigned integers as unsigned. Adds a `uint64` writer id.
- [moetemp#73](moetemp#73): Build a returned proto-wire resource in an endpoint-less TypeScript client. Makes `open-writer` return the `writer` resource.

#262 adds a `status` enum to the holder record once it merges.
@moetemp

moetemp commented Oct 23, 2026

Copy link
Copy Markdown
Owner Author

Upstreamed as temporalio#281.

@moetemp moetemp closed this Oct 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant