Skip to content

Commit 17d49af

Browse files
committed
Remove stale future-query wording from the current Python API reference
1 parent 877c2d0 commit 17d49af

4 files changed

Lines changed: 145 additions & 9 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,9 @@ Earlier SDK versions remain historical releases and are not alternate supported
5555
`NamespaceDescription.deleted`.
5656

5757
### Fixed
58+
- The Python API reference now describes query decorators and query-state
59+
replay as parts of the shipped server-routed worker query path while keeping
60+
its Server capability negotiation requirements explicit.
5861
- Workflow and update-validation discovery now use one Server-multiplexed long
5962
poll per workflow reservation. A worker with one workflow slot can discover
6063
either task kind promptly without leasing excess replay work, increasing idle

‎scripts/ci/test-validate-regression-corpus.py‎

Lines changed: 73 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -378,6 +378,32 @@ def test_malformed_golden_wire_must_be_canonical_base64(self) -> None:
378378
VALIDATOR._avro_golden_fixture(fixture, "golden.json")
379379

380380

381+
class PythonSemanticNeutralityTest(unittest.TestCase):
382+
def test_module_class_and_function_docstrings_are_source_trivia(self) -> None:
383+
base = '''\
384+
"""Base module documentation."""
385+
386+
class Replayer:
387+
"""Base class documentation."""
388+
389+
async def replay(self, history):
390+
"""Base function documentation."""
391+
return tuple(history)
392+
'''
393+
current = '''\
394+
"""Current module documentation."""
395+
396+
class Replayer:
397+
"""Current class documentation."""
398+
399+
async def replay(self, history):
400+
"""Current function documentation."""
401+
return tuple(history)
402+
'''
403+
404+
self.assertTrue(VALIDATOR._python_change_is_semantically_neutral(base, current))
405+
406+
381407
class WorkerCodecGuardTest(unittest.TestCase):
382408
def setUp(self) -> None:
383409
self.temporary = tempfile.TemporaryDirectory(prefix="regression-corpus-worker-guard-")
@@ -396,6 +422,12 @@ def _command_payload_codec(codec):
396422
return codec or "avro"
397423
398424
425+
def replay_history(history):
426+
'''Replay durable history into a stable sequence.'''
427+
mode = "replay-history"
428+
return mode, tuple(history)
429+
430+
399431
class Worker:
400432
async def validate_update(self, history, codec, approved):
401433
codec = _validate_payload_codec(codec)
@@ -499,11 +531,49 @@ def test_ignored_update_symbol_does_not_count_as_replay_change(self) -> None:
499531

500532
self.assertFalse(self._replay_guard_matches())
501533

502-
def test_nonignored_history_symbol_still_counts_as_replay_change(self) -> None:
534+
def test_docstring_only_edit_inside_replay_symbol_is_neutral(self) -> None:
535+
source = self.root / "src/durable_workflow/worker.py"
536+
source.write_text(
537+
source.read_text(encoding="utf-8").replace(
538+
"Replay durable history into a stable sequence.",
539+
"Reconstruct durable history for a query.",
540+
),
541+
encoding="utf-8",
542+
)
543+
544+
self.assertFalse(self._replay_guard_matches())
545+
546+
def test_logic_edit_inside_replay_symbol_remains_related(self) -> None:
547+
source = self.root / "src/durable_workflow/worker.py"
548+
source.write_text(
549+
source.read_text(encoding="utf-8").replace(
550+
"return mode, tuple(history)",
551+
"return mode, list(history)",
552+
),
553+
encoding="utf-8",
554+
)
555+
556+
self.assertTrue(self._replay_guard_matches())
557+
558+
def test_non_docstring_literal_edit_inside_replay_symbol_remains_related(self) -> None:
503559
source = self.root / "src/durable_workflow/worker.py"
504560
source.write_text(
505-
source.read_text(encoding="utf-8")
506-
+ "\n\ndef replay_history(history):\n return tuple(history)\n",
561+
source.read_text(encoding="utf-8").replace(
562+
'mode = "replay-history"',
563+
'mode = "strict-replay-history"',
564+
),
565+
encoding="utf-8",
566+
)
567+
568+
self.assertTrue(self._replay_guard_matches())
569+
570+
def test_unparseable_python_change_remains_related(self) -> None:
571+
source = self.root / "src/durable_workflow/worker.py"
572+
source.write_text(
573+
source.read_text(encoding="utf-8").replace(
574+
'mode = "replay-history"',
575+
'mode = "replay-history',
576+
),
507577
encoding="utf-8",
508578
)
509579

‎scripts/ci/validate-regression-corpus.py‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1205,6 +1205,59 @@ def _smallest_changed_python_symbols(
12051205
]
12061206

12071207

1208+
def _strip_python_docstrings(tree: ast.AST) -> None:
1209+
for node in ast.walk(tree):
1210+
if not isinstance(
1211+
node,
1212+
ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef,
1213+
):
1214+
continue
1215+
if (
1216+
node.body
1217+
and isinstance(node.body[0], ast.Expr)
1218+
and isinstance(node.body[0].value, ast.Constant)
1219+
and isinstance(node.body[0].value.value, str)
1220+
):
1221+
del node.body[0]
1222+
1223+
1224+
def _python_change_is_semantically_neutral(base_source: str, current_source: str) -> bool:
1225+
"""Compare Python syntax while excluding actual docstrings and source trivia."""
1226+
1227+
try:
1228+
base_tree = ast.parse(base_source)
1229+
current_tree = ast.parse(current_source)
1230+
except SyntaxError:
1231+
return False
1232+
1233+
_strip_python_docstrings(base_tree)
1234+
_strip_python_docstrings(current_tree)
1235+
return ast.dump(base_tree, include_attributes=False) == ast.dump(
1236+
current_tree,
1237+
include_attributes=False,
1238+
)
1239+
1240+
1241+
def _python_file_change_is_semantically_neutral(
1242+
root: Path,
1243+
base_ref: str,
1244+
path: str,
1245+
) -> bool:
1246+
if not path.endswith(".py"):
1247+
return False
1248+
current_path = root / path
1249+
if not current_path.is_file():
1250+
return False
1251+
base_source = _run(["git", "show", f"{base_ref}:{path}"], root, check=False)
1252+
if not base_source:
1253+
return False
1254+
try:
1255+
current_source = current_path.read_text(encoding="utf-8")
1256+
except (OSError, UnicodeDecodeError):
1257+
return False
1258+
return _python_change_is_semantically_neutral(base_source, current_source)
1259+
1260+
12081261
def _changed_content(
12091262
root: Path,
12101263
base_ref: str,
@@ -1279,6 +1332,7 @@ def _guard_matches(
12791332
) -> bool:
12801333
guard = _object(raw_guard, "guard")
12811334
matching = sorted(path for path in changed if _matches(path, _string(guard["glob"], "guard.glob")))
1335+
matching = [path for path in matching if not _python_file_change_is_semantically_neutral(root, base_ref, path)]
12821336
if not matching:
12831337
return False
12841338
patterns = guard.get("content_patterns")

‎src/durable_workflow/workflow.py‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -122,9 +122,14 @@ def query(name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
122122
"""Mark a workflow method as a read-only query handler.
123123
124124
Query methods are invoked against replayed workflow state. They must not
125-
mutate ``self`` or perform I/O. The server-side worker query transport is
126-
still implemented separately; this decorator records the Python receiver
127-
metadata and is used by :func:`query_state`.
125+
mutate ``self`` or perform I/O. The server-routed worker query path uses
126+
this decorator's receiver metadata and :func:`query_state` to select and
127+
invoke the handler after replaying durable history.
128+
129+
Workers advertise ``query_tasks`` only after Server discovery reports
130+
``worker_protocol.server_capabilities.query_tasks: true``. Clients check
131+
the same capability before dispatch and raise a typed capability or
132+
discovery error when the query path is unavailable.
128133
"""
129134

130135
def wrap(method: Callable[..., Any]) -> Callable[..., Any]:
@@ -1850,9 +1855,13 @@ def query_state(
18501855
) -> Any:
18511856
"""Replay a workflow to current state and invoke a registered query.
18521857
1853-
This is the Python-side core that a future server-routed query task can
1854-
call after fetching durable history. Unknown query names and handler
1855-
exceptions are normalized to :class:`~durable_workflow.errors.QueryFailed`.
1858+
This is the replay and invocation core used by the current server-routed
1859+
worker query path after it fetches durable history. That path is negotiated
1860+
through ``worker_protocol.server_capabilities.query_tasks``: workers
1861+
advertise ``query_tasks`` only after discovery reports it as available,
1862+
and clients fail with typed capability or discovery errors when it is not.
1863+
Unknown query names and handler exceptions are normalized to
1864+
:class:`~durable_workflow.errors.QueryFailed`.
18561865
"""
18571866
try:
18581867
state = _replay_state(

0 commit comments

Comments
 (0)