Emit runtime device interface as a module

[glopesdev]

This is an alternative to #16, stacked on the same #15 head, so the diff is the single commit that separates the two designs. It gives registers the by-name access #16 adds, using the module they already live in, and keeps REGISTER_MAP as the address view.

What this changes

create_device becomes create_module and returns a module rather than a Device subclass:

behavior = create_module(Path("device.yml").read_text())

behavior.AnalogData            # by name
behavior.REGISTER_MAP[44]      # the same class, by address
behavior.WHO_AM_I              # device identity, from the schema

The schema registers are merged with the common Harp ones at module level, so a schema-built device is reached exactly the way a generated package is. The module is not registered in sys.modules, so the caller binds it, and two schemas may share a device name without clashing.

Device carries no register collection at all. read, write and subscribe already take a register class, and subscribe records the class the caller passed, so nothing inside harp-device ever needed to look a register up by address.

Why a module

#16 requires a generated package to emit each register at module scope, and then a namespace class re-declaring every one of them as AnalogData = AnalogData. The module namespace produced by the first step is already a complete mapping from name to class; the second step builds a second one beside it so that it can be typed. A module is the container Python already has for a collection of types, and every type checker and REPL handles it without help.

What that removes: RegisterMap and CoreRegisters, 203 lines whose job is attribute access, by_name, by_address, iteration, in, len and __dir__; the Device type parameter and its PEP 696 default, threaded through harp-device, harp-data and harp-serial; and the typing-extensions runtime dependency that default requires. Measured under src/, this branch is +205 / -369 against #16.

A module is honestly worse in one place. One built at runtime is invisible to a type checker, so the schema-driven path gets no static types. #16 resolves those names to type[RegisterBase[Any]], so read returns ParsedHarpMessage[Any] on that path in either design and the payload type is unknown both ways. The difference is confined to the statically generated path, where a real module on disk autocompletes and type-checks with no machinery behind it.

What downstream code generators must emit

Nothing new. Register classes at module scope and a REGISTER_MAP spreading the core map, which is what they emit today, plus optionally a Device subclass setting __whoami__.

tests/device/expected_device.py is a checked-in sample of generator output and is unchanged by this branch. harp-tech/generators#119 needs no change, whereas #16 forbids it from emitting REGISTER_MAP and requires the namespace class instead.

Collision rule

A device register now displaces the common register it collides with from both views at once, by address or by name. A schema claiming address 0 leaves its own register at REGISTER_MAP[0] and drops WhoAmI from the module, so a name and the address map can never disagree about what sits at an address. The earlier behavior would keep both names live and pin only the address half.

Dataset reader

DatasetReader takes a module in place of a device class and reads REGISTER_MAP off it, so reader.read still accepts either a register class or an address. create_dataset_reader is unchanged from the outside.

Testing

The full suite passes at 267 tests, with ruff, pyright, codespell and mkdocs build --strict clean. Every assertion in the old test_device_emit.py carries over to test_create_module.py, with new cases for name reachability, __all__, the sys.modules guarantee, and the invariant that the name and address views agree.

[bruno-f-cruz]

Looks good. Mostly just wondering if we should abandon the bare "module" name in favor of "*_device_module" everywhere. Otherwise small question regarding a type hint.

[bruno-f-cruz]

Two final small notes and ready to merge this and all the underlying PRs.