Early client impl and docs scaffolding#5
Closed
cretz wants to merge 16 commits intotemporalio:mainfrom
Closed
Conversation
# Conflicts: # tests/api/test_grpc_stub.py
…date python version in CI
…orker-impl in submodule
Contributor
Author
|
Note, this is not cleanly applying on top of what's in main, so I'll be opening a new PR from a different branch when we're ready for full review |
Contributor
Author
|
Since there have been no comments here, I am going to close this and make a new branch properly rebased on main. |
Contributor
Author
|
Moved to #6 |
bergundy
reviewed
Feb 7, 2022
Member
bergundy
left a comment
bergundy
left a comment
There was a problem hiding this comment.
I forgot to submit this in progress review.
| @@ -0,0 +1,18 @@ | |||
| .. _api: | |||
Member
There was a problem hiding this comment.
Can we use markdown?
I haven't looked into it much but there seems to be a markdown extension for sphinx https://www.sphinx-doc.org/en/master/usage/markdown.html.
The reasoning is that markdown is much more popular and well known but that might not apply in the case of sphinx docs.
I know rst is the standard for python docs so feel free to ignore this comment.
| import os | ||
| import sys | ||
|
|
||
| sys.path.insert(0, os.path.abspath("../")) |
Member
There was a problem hiding this comment.
This is relative to PWD, use os.path.abspath(os.path.join(os.path.dirname(__file__), '..')) to make it relative to the file.
| @@ -0,0 +1,69 @@ | |||
| # Configuration file for the Sphinx documentation builder. | |||
Member
There was a problem hiding this comment.
Are you eventually planning to put this on readthedocs.org?
jssmith
added a commit
that referenced
this pull request
Apr 23, 2026
Reconciles DESIGN-v2.md with the "Streaming API Design Considerations" Notion page so both track the authoritative Python implementation. The Notion page had richer narrative (durable-streams framing, pull-vs-push reasoning, one-way-door callouts, offset-options comparison table, alternatives-considered list for wire evolution, end-to-end-principle writeup). This change brings that into the in-repo doc. Changes: - New top-of-doc note establishing that the Python code in sdk-python/temporalio/contrib/pubsub/ is authoritative; both DESIGN-v2.md and the Notion page track it. - New Decision #1 "Durable streams" explaining the durable-by-default choice vs ephemeral streams (simpler model, reliability, correctness). Existing decisions renumbered. - Decision #4 (Global offsets) gains the 6-option ecosystem comparison table and a one-way-door callout flagging the wire-protocol commitment. - Decision #9 (Subscription is poll-based) expanded with the pull-vs-push trade-off (back-pressure, subscriber-controlled read position, data-at-rest) and explicit "both layers are exposed" framing. - New "Design Principles" section with the Saltzer/Reed/Clark end-to-end-dedup framing and the "retries remain in the log" contract, with a one-way-door callout on the append-only-of-attempts contract. - Compatibility section gains a full alternatives-considered list (version field, versioned handler names, protocol negotiation, SDK version embedding, accepting silent incompatibility) and a two-part one-way-door callout on immutable handler names + no version field. - New "Ecosystem analogs" section: a compact one-paragraph summary (NATS JetStream for offsets, Kafka for idempotent producers, Redis for blocking pull, Workflow SDK as the durable-execution peer) with a pointer to the Notion page for the full comparison tables. The Notion page itself is still behind on the Payload migration (Decision #5 "Opaque message payloads" needs rewriting, API signatures still show priority= and data: bytes). That update is deferred pending resolution of an open reviewer discussion on activity-retry/dedup (discussion 34a8fc56-7738-808c-b29b-001c5066e9d2) whose substance overlaps with the Decision #5 rewrite. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was changed
I have opened this early PR for review. I still have things of course to do such as: