Skip to content

feat(sdk): client.plan(...) gives the request a call would send, and with_options sets a call's options - #577

Merged
bim-ba merged 1 commit into
mainfrom
feat/sdk-plan
Oct 10, 2026
Merged

bim-ba merged 1 commit into
mainfrom
feat/sdk-plan

Conversation

@bim-ba

@bim-ba bim-ba commented Oct 10, 2026 •

Copy link
Copy Markdown
Owner

The SDK's way to ask "what would this send": client.plan(...) returns the request as a value. Decision: #556 (question 2, B). With it, client.with_options(...), which the plan is built on.

planned = tracker.plan(lambda tracker: tracker.boards.delete(31))
planned.method, planned.url          # ('DELETE', 'https://api.tracker.yandex.net/v3/boards/31')
planned.grants_access                # False

patient = tracker.with_options(timeout_seconds=120, retries=5)
patient.issues.get("DE-7")

plan(call)

What it returns PlannedRequest: the method, the URL and the body of the FIRST write call would send, secrets masked by the function the CLI's --dry-run uses
Reads inside call go out for real, up to the first write; nothing after that write runs
A call that sends no write YandexInvalidRequestError: "the call sends no write: nothing to plan"
A request that would grant access planned.grants_access is True
The client itself unchanged: call is given a view of it under dry_run

The docstring says so with an input -> output example that runs as a doctest (a delete planned, and the error for a read).

It is one mechanism on three surfaces: the core stops the first write under dry_run and raises RequestPlanned (#557); the CLI's command wrapper catches it, the MCP server's layer catches it (#576), and here plan does.

with_options(timeout_seconds=, retries=, dry_run=)

Not in the ten lines of #556, which called it: it did not exist. It is the per-call options of the SDK (the accepted idea, taken whole as #556 said: timeout, retries, dry run).

  • A view: the same connections and credentials, the resources wired over a session with the options. Nothing is opened; a view has nothing of its own to close, and leaving a with on it does not close the client it came from.
  • One option changed keeps the others, so a view of a view works.
  • The options are validated like the configuration they stand in for (retries=-1, timeout_seconds=0 are refused).
  • The timeout is put on each request of the view; the client's own is untouched.
  • SyncSession.with_options and AsyncSession.with_options are the same thing one level down.

The asynchronous side

There is no asynchronous domain client in ycli (the asynchronous how-to works with connect_async and endpoints), so there is no asynchronous plan. The asynchronous session has with_options, tested: under dry_run=True a write raises RequestPlanned and a read goes out.

Shared with #576

core/guard.py: a plan that is only shown now says whether its request grants access. The lines are the same as in #576, word for word, so whichever lands second merges without a conflict (checked: git merge-tree of the two heads has none).

Can plan send?

with_options copies the client and wires its resources over the view's session. plan is safe only if nothing reachable from the view still holds the session of the client.

Check What it holds Seen failing
a walk over every object reachable from a view that holds a session, for each of the four domain clients, to any depth (attributes, lists, tuples, dicts) each holds the VIEW's session, and no holder is the same object as the client's own one real sub-client made not to be rebuilt (self.boards = getattr(self, "boards", None) or …): the walk names client.boards._session, and two plan tests fail with it
the same walk on a client made to keep a resource outside what a view rebuilds, nested in a list of a dict the stale object is named -
tests/contract/test_sdk_plan.py: every contract case that writes, called through client.plan(...) no write reaches the mock; where the case has a command, the plan equals what --dry-run -o json prints -
after a plan and beside a dry-run view the client's own write is sent; a view with dry_run=False made from a dry-run view sends -
call raises before any write (a 404 on a read inside it, or an error of the caller's own) raised as itself, not as "nothing to plan" -

Coverage of the drive: 406 write cases of 264 operations, all of them through client.plan; 396 have a command and are compared with its plan, 10 have none and are held to "no write sent" only.

Tests

  • a plan of a call that reads, updates, then deletes: the read is sent, the update is returned, the delete never runs; the same delete through the client itself is sent
  • no write: the error; a grant: grants_access
  • a view: same connection pool, its own retries and timeout (on the request), the parent untouched, a view of a view, invalid options refused, a view does not close the parent
  • dry_run on and off for a view; the asynchronous session

Verified

On this head, over main 6b6c1787 (0.140.0; the commit's parent, by hash): ruff, ty, lint-imports, ast-grep (each by exit code, 0), the commit hooks over the commit (exit 0), rulesync and the generated reference without drift; the full suite: 7467 passed, 5 skipped, coverage 100 %.

Seen once and not again, not traced: in one partial run a snapshot test (mcp_output_schemas, wiki_grids_create) failed with another hash; regenerating the snapshot changed nothing and three later runs, the full suite among them, passed.

NOT RUN: any live run.

🤖 Generated with Claude Code

…d `with_options` sets a call's options

`tracker.plan(lambda tracker: tracker.issues.update(...))` returns the first
write the call would send, not sent: its method, URL and body with secrets
masked, and whether it would grant access (#556, question 2). What the call
reads before that write is read for real; nothing after it runs. A call that
sends no write is an error: there is nothing to plan.

It is the SDK's side of one mechanism: the core stops the first write under
`dry_run` and raises `RequestPlanned` (#557); the CLI's command wrapper and the
MCP server's layer catch it, and here `plan` does, so a caller gets a value and
catches nothing.

`client.with_options(timeout_seconds=..., retries=..., dry_run=...)` is the
client for the calls made through what it returns: a view over the same
connections and credentials, with nothing of its own to close. The options are
validated like the configuration they stand in for. A session has the same
method, the asynchronous one too.

A plan that is only shown now says whether its request grants access, as one
that is asked about did: the same lines as in the `dry_run` change of the MCP
server.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was previously deployed

1 inactive deployment
yandex-e2e — ae3308b4 Deployed Oct 10, 2026 by bim-ba via live (all) #713
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