Change `replace_kwargs_using` so it will create keyword-only params for wrapped variadic

[thorwhalen]

Change replace_kwargs_using so it will create keyword-only params for wrapped variadic

[thorwhalen]

Checked on master (0.1.74) during a cloud sweep. The keyword-only part of this looks done already: commit f84b5a9 (2025-10-11, after this issue was filed) makes every param injected from the source signature keyword-only, and the docstring shows it ((a, b, c, *, x: int, y=2, z=3, **extra_apple_options)).

One case still behaves oddly, which may be what "wrapped variadic" meant. A *args in the source becomes a required keyword-only param:

def apple_vp(a, *args, z=3, **extra): ...

@replace_kwargs_using(apple_vp)
def sauce(a, **kw): ...

Sig(sauce)  # (a, *, args, z=3, **extra)

sauce forwards through **kw, so it can never forward positional values into apple_vp's *args. Two options:

1. Drop a source VAR_POSITIONAL from the injected params. That's the natural fix.
2. Keep args but give it a default of ().

Either one changes existing signatures, so it isn't purely additive. I left it for your decision and didn't change code. If the keyword-only behaviour was all this issue asked for, it can be closed.

---

Generated by Claude Code

[thorwhalen]

Decision: drop a source *args from the injected params (option 1)

Options considered

1. Drop the source VAR_POSITIONAL from the injected params.
2. Keep it, as keyword-only args=().
3. Leave as is: a required keyword-only args.

Evidence (0.1.74)

def apple_vp(a, *args, z=3, **extra): ...

@replace_kwargs_using(apple_vp)
def sauce(a, **kw): return apple_vp(a, **kw)

Sig(sauce)                   # (a, *, args, z=3, **extra)
sauce(1, args=(2,), z=4)     # apple_vp gets extra={'args': (2,)} -- silently wrong

With a source that has no **kwargs, the same call raises inside the source (got an unexpected keyword argument 'args'). Either way the injected args is a parameter the target can never forward: it only has **kwargs to forward with, and a *args can't be filled by keyword. Options 2 and 3 both advertise it anyway.

Use sites. Every replace_kwargs_using / Sig.replace_kwargs_using call across i2 and its 102 local dependents was inventoried (oa: 8 sites on the OpenAI SDK and local wrappers, aix: 1, i2 internal). None has a source with a *args, so option 1 changes no existing signature in the fleet. For the fleet it is a pure signature change anyway: the target keeps the source's **kwargs, so what a call does at runtime is unchanged.

Rationale. A signature should only advertise what can be given. Dropping the *args is the honest signature and is additive for every real use.

Follow-up, not changed here. A source positional-only param has the same problem in a weaker form: replace_kwargs_using(lambda a, b, /, c, **kw: ...) on sauce(a, **kw) gives (a, *, b, c, **kw), and forwarding b by keyword fails in the source. That one hides a required param if dropped, so it needs its own decision (probably: raise). Left open, in a separate issue if wanted.

Where. Implemented in the branch that also resolves #93 (stacked on #92, PR to follow), with a doctest and test_replace_kwargs_using_drops_a_source_var_positional. The keyword-only injection that this issue originally asked for was already in 0.1.74 (f84b5a9) and is now pinned by a test too.