Skip to content

fix: Respect variance, unions and Any when matching devices to plans - #2

Open
DiamondJoseph wants to merge 2 commits into
mainfrom
fix-device-generic-variance
Open

DiamondJoseph wants to merge 2 commits into
mainfrom
fix-device-generic-variance

Conversation

@DiamondJoseph

@DiamondJoseph DiamondJoseph commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Fixes how blueapi decides whether a device satisfies a plan parameter annotated with a parameterised device type such as Movable[int], and fixes GET /devices and GET /plans for the same cases. There is no linked issue. This targets the fork for review and has not been proposed upstream.

Why

is_compatible_args in core/context.py compared every type argument with issubclass(declared, annotated), whatever variance the annotated type declares. bluesky declares Movable (and Checkable) as contravariant in the value it is given, so for those the check was backwards: a Movable[int] parameter accepted a Movable[bool] device and rejected a Movable[object] one.

Fixing that exposed four related defects on the same path:

  • A union in a type argument raised TypeError or AttributeError instead of being compared.
  • Any in an annotation was compared as if it were an ordinary class.
  • One device declaring a union made GET /devices fail for every device.
  • One plan annotated with a union type argument made GET /plans fail for every plan.

Behaviour before and after

Measured, not inferred, by loading tests/unit_tests/core/fake_generic_module.py through config sources on each side. Rows are what the device's class declares. Columns are the annotation of the plan parameter.

Upstream main (1e761f9)

Device declares m: Movable m: Movable[Any] m: Movable[int] m: Movable[int] | Movable[str] m: Movable[int | str]
nothing accept accept accept accept accept
Movable[Any] accept accept accept accept accept
Movable[object] accept reject reject reject AttributeError
Movable[int | str] accept TypeError TypeError TypeError accept
Movable[int] accept reject accept accept accept
Movable[str] accept reject reject accept accept
Movable[bool] accept reject accept accept accept

With that module loaded, GET /devices and GET /plans both raised AttributeError: 'types.UnionType' object has no attribute '__name__'.

This branch

Device declares m: Movable m: Movable[Any] m: Movable[int] m: Movable[int] | Movable[str] m: Movable[int | str]
nothing accept accept accept accept accept
Movable[Any] accept accept accept accept accept
Movable[object] accept accept accept accept accept
Movable[int | str] accept reject accept accept accept
Movable[int] accept reject accept accept reject
Movable[str] accept reject reject accept reject
Movable[bool] accept reject reject reject reject

Both endpoints return normally.

This can reject requests that used to be accepted

Reviewers should decide whether this needs fix!:. The cells that went from accept to reject are:

  • A device declaring a subtype of a consumed type: Movable[bool] for a Movable[int] parameter, including through Movable[int] | Movable[str]. The realistic form is a plan annotated Movable[SomeEnumBase] given a device that only takes one enum subclass.
  • A device that takes only some members of a union: Movable[int], Movable[str] or Movable[bool] for a Movable[int | str] parameter.

The cells that went from reject or error to accept are:

  • A device declaring a supertype of a consumed type: Movable[object] for every Movable[...] parameter. The realistic form is a Movable[str] device for a plan annotated Movable[SomeStrEnum].
  • A device declaring a union, Movable[int | str], for Movable[int] and for Movable[int] | Movable[str].

The rules as implemented

  1. Only declared type arguments are checked. A device whose class declares none for the annotated type is accepted, as before.
  2. Each type argument is compared using the variance of its own type parameter, read from __parameters__ of the annotated type.
    • Contravariant, meaning the device consumes the value: the device must accept at least what the annotation asks for, so annotated must be a subtype of declared.
    • Covariant or invariant: declared must be the same as, or a subtype of, annotated. This is the old rule.
  3. Unions are compared member by member. A union is a subtype of something if every member is. Something is a subtype of a union if it is a subtype of any member.
  4. Any means different things on each side.
    • In the annotation it means the plan may use any value, so it is treated as object. Movable[Any] accepts only a device that can be set to anything. Readable[Any] accepts any Readable.
    • Declared by the device it is trusted, so the device is accepted for every type argument. This is unchanged.
  5. A type variable on either side is compatible with everything, as before.
  6. Types that cannot be compared with issubclass are compatible only if equal. list[int] satisfies list[int] and not list[bool]. This used to raise TypeError.
  7. Movable[int] | Movable[str] is a union of two annotations, validated by pydantic one member at a time, so each member follows the rules above.

Error message

When the device is the right kind but declares the wrong type arguments, the message now says what it declares:

Device int_mover (tests.unit_tests.core.fake_generic_module.IntMover) is not of type bluesky.protocols.Movable[int | str], it is a bluesky.protocols.Movable[int]

On main this case was accepted. Other mismatches involving a union reported issubclass() arg 1 must be a class, or escaped as AttributeError. For a union of annotations pydantic reports one such error per member.

Endpoints

  • GET /devices: ProtocolInfo.types used arg.__name__. A union has none on Python 3.11 to 3.13, so one device declaring Movable[int | None] broke the listing. On 3.14 it has one, which is just Union. Unions are now named member by member, for example "int | str". Anything else without a name falls back to str().
  • GET /plans, two changes:
    • A union type argument in an annotation no longer raises. It appears in the parameter's types as "int | str".
    • The enum of device names for a parameter used to list every device of the right kind, ignoring type arguments, so it offered devices the plan would then reject. It now lists only devices the parameter accepts. A test asserts that the offered set equals the accepted set for every plan.
  • The OpenAPI schema is unchanged, so REST_API_VERSION is not bumped. Regenerating it produces no diff.

Edge cases and decisions

Each of these was checked by running it, unless it says otherwise.

  • Invariant type parameters are still compared covariantly. bluesky declares Readable, Configurable and Subscribable invariant, although Readable only produces values. Strict invariance would reject Readable[bool] for Readable[int], which is harmless, so the old leniency is kept and a test pins it.
  • Movable[object] is accepted for Movable[Any]. A device declared that way can be set to anything, and it already satisfies Movable[int | str]. This goes slightly beyond "only Movable[Any] or Movable". It is one condition to remove if unwanted.
  • Readable[Any] now accepts any Readable. On main it rejected a device declaring Readable[bool], by the same rule that rejected the Movable[Any] cases. That exact case was not run on main.
  • A class can have more type arguments than type parameters, for example one that only defines __class_getitem__. The extra arguments are compared covariantly, as before, so nothing is silently skipped.
  • Positions are respected for several type parameters. A Converter[T_contra, T_co] is checked contravariantly in the first argument and covariantly in the second.
  • Unresolved forward references, such as class LaterMover(Movable["Later"]):
    • They are accepted by bare Movable and rejected by Movable[int] and Movable[Any], because they cannot be compared.
    • They are shown as ForwardRef('Later') in the error message and in GET /devices. That is accurate but not pretty.
    • Naming them needed the str() fallback. Without it, building the new error message would itself raise AttributeError.
  • Python versions. On 3.11 to 3.13 int | str is a types.UnionType, while a union of two parameterised types such as Movable[int] | Movable[str] is a typing union. On 3.14 both are typing.Union. is_union recognises all of them. The matching and naming helpers were run on 3.11, 3.12, 3.13 and 3.14. The full suite was run on 3.13 only.
  • is_compatible_args no longer raises for arguments that are not classes. It returns False, which becomes the normal "is not of type" rejection.
  • Type variable names are unchanged in GET /devices. A device with an unbound type argument still reports the variable's name, and Any reports "Any".

Known limitations that this does not change

  • Most real ophyd-async devices are not checked at all. Only the class's own generic bases for exactly the annotated type are read.
    • SimMotor and a SignalRW[int] both declare nothing for Movable directly.
    • So a Movable[str] parameter accepts both of them.
    • The check bites for classes written as class Shutter(StandardReadable, Movable[ShutterState]).
  • A subclass that adds generic bases of its own hides its parent's declaration and becomes unchecked. A subclass with no generic bases inherits it.
  • The numeric tower is not modelled. A type checker accepts Movable[float] where Movable[int] is asked for, because an int is acceptable as a float. issubclass(int, float) is false, so blueapi rejects it, as it did on main.
  • PEP 695 classes (class Foo[T], Python 3.12 or later) have inferred variance, which is not visible on the type parameter. Their arguments are compared covariantly.
  • Nested arguments are dropped from names. Movable[list[int]] is shown as Movable[list], as before.

Changes by file

  • src/blueapi/core/context.py
    • is_compatible_args applies the rules above, using new private helpers _contravariant_parameters and _is_subtype.
    • New public is_union, shared with service/model.py.
    • qualified_name names unions and falls back to str() for anything without a name.
    • The device reference validator adds the "it is a" clause, and its schema enum uses is_compatible.
  • src/blueapi/service/model.py: _type_name replaces arg.__name__.
  • docs/explanations/type_validators.md: new section "Type Arguments of Devices", covering variance, Any, the two union forms, the error message and the schema.
  • tests/unit_tests/core/fake_generic_module.py: seven ophyd-async devices built by a dodal DeviceManager, and five plans.
  • tests/unit_tests/core/test_context.py, tests/unit_tests/service/test_rest_api.py, new tests/unit_tests/service/test_model.py.

Testing

126 test cases are added. Before this work is_compatible_args had no direct tests.

  • Unit level, on is_compatible_args with stand-in generic classes: covariant, contravariant and invariant parameters against a subtype, the same type, a supertype and an unrelated type, plus unions, Any on each side, mixed variance, uncomparable types and missing type arguments.
  • Through a plan's model, with plain classes that implement Movable structurally: each annotation against each device, including the exact error text.
  • Loaded the way the server loads them, from a module through DeviceManagerSource and PlanSource: all 35 plan and device pairs, and a check that each plan's schema offers exactly the devices it accepts.
  • Through the endpoints, with the dispatcher mocked to call the interface in-process: GET /devices and GET /plans, asserting the full type and device lists.

Run locally on Python 3.13:

  • The unit suite: 1,016 passed, with the helm-dependent tests excluded because the machine has no helm.
  • pyright: 0 errors.
  • The ruff and gitleaks hooks on the changed files.
  • The docs build with warnings as errors.
  • Coverage: every new line in context.py and model.py is executed.

Not run: the helm tests, the system tests, and the helm and lock-file pre-commit hooks.

Related

Instructions to reviewer on how to test:

  1. Run pytest tests/unit_tests/core/test_context.py tests/unit_tests/service/test_rest_api.py tests/unit_tests/service/test_model.py.
  2. Compare the "This branch" table above with ACCEPTED_MOVERS in tests/unit_tests/core/test_context.py, which is what the loaded-device tests assert.
  3. Build the docs with tox -e docs and read "Type Arguments of Devices" in explanations/type_validators.html.
  4. Decide on the three judgement calls: lenient invariance, Movable[object] for Movable[Any], and the narrower enum in plan schemas.

Checks for reviewer

  • Would the PR title make sense to a user on a set of release notes

🤖 Generated with Claude Code

Assisted-by: Claude Fable 5.2 via Claude Code

Joseph Ware and others added 2 commits November 16, 2026 19:16
Device type arguments were compared with issubclass(declared, annotated)
whatever variance the annotated type declares. bluesky declares Movable
as contravariant, so a Movable[int] parameter accepted a Movable[bool]
device and rejected a Movable[object] one.

- Compare each type argument using the variance of its type parameter
- Compare unions member by member instead of raising TypeError
- Treat Any in an annotation as "must work with everything", so that
  Movable[Any] accepts only a device that can be set to anything
- Say what a rejected device declares in the error message
- Name unions in messages and plan schemas instead of raising
  AttributeError
- Offer in the schema of a plan only the devices its parameter accepts

Document the rules in docs/explanations/type_validators.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Assisted-by: Claude Fable 5.2 via Claude Code
DeviceModel.from_device used the __name__ of each type argument. A
union such as int | str does not have one, so a single device declaring
a union made GET /devices fail. Name each member of a union, and fall
back to the string form of anything else without a name.

Test GET /devices and GET /plans against devices and plans loaded from
a module in the same way as the server loads them.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Assisted-by: Claude Fable 5.2 via Claude Code

`Movable` with no type arguments accepts any `Movable` device.

`Any` is not a way to switch the check off. `Movable[Any]` says that the plan may set the device to anything, so it accepts only a device that can be set to anything: one declared as `Movable[Any]` or `Movable[object]`, or one that declares no type argument. For a type that only produces values the opposite holds, so `Readable[Any]` accepts any `Readable` device.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any is not a way to switch the check off. Movable[Any] says that the plan may set the device to anything, so it accepts only a device that can be set to anything: one declared as Movable[Any] or Movable[object], or one that declares no type argument

Is this true? I was under the impression this was how it worked (see 2116 in bluesky) but I don't think it does any more. Passing a Movable[int] to a function that accepts a Movable[Any] will type check as valid but fail at runtime.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Definitely with the changes, Movable[int] into Movable[Any] should not go: your function could have

def f(m: Movable[Any]) -> MsgGenerator:
  m.set(1)
  m.set("banana")
  m.set({})

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But run that through a type checker and it passes?

@DiamondJoseph DiamondJoseph Nov 17, 2026 •

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It passes type checking because Any returns True for any check, but for purposes of a typevar in the method signature, it shouldn't and blueapi should be more strict than that. If you want Any Movable, the type should be Movable. Movable[object] or Movable[Any] is only for a Movable that can be set to anything.

Whether a value of type sub can be used where one of type sup is expected, as
far as that can be told at run time.

Any and type variables are compatible with everything, and everything can be

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

type variables are compatible with everything

If we ignore bounds and constraints?

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lemme add a test and find out

This branch has not been deployed

No deployments
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.

2 participants