Skip to content

Split harp.device into core, client and schema - #21

Merged
glopesdev merged 1 commit into
mainfrom
refactor-device-namespace
Aug 12, 2026
Merged

Split harp.device into core, client and schema#21
glopesdev merged 1 commit into
mainfrom
refactor-device-namespace

Conversation

@glopesdev

Copy link
Copy Markdown
Contributor

harp.device becomes an empty PEP 420 namespace so that a device package can be harp.device.<name>, sitting beside the library portions rather than in a separate harp.devices tree that differs by one character.

harp is already a namespace, since no distribution ships harp/__init__.py. This does the same one level down. The requirement is that nothing ships harp/device/__init__.py, which harp-device did until now.

The three portions

harp/device/core/     the core register set every device carries
harp/device/client/   talking to a device
harp/device/schema/   building a device interface from a device.yml

core holds the 15 core registers, their 4 payload classes, 4 enums and REGISTER_MAP. client holds Device, Subscription, EventHandler, ITransport, TransportError and HarpFramer. schema holds create_device_module, parse_device_schema, DeviceModule, DeviceModuleLike and ConverterContext.

The split follows the dependency graph rather than cutting across it. core imports nothing from the other two, and client and schema each depend only on core, so there are no cycles and no module had to be divided.

harp-device remains a single distribution shipping all three portions. Nothing changes at the packaging level beyond dropping the __init__.py.

Why the names

core is the term this ecosystem already uses for the register set in core.yml, so harp.device.core.WhoAmI reads as it should. That is also the reason the device runtime did not go there. Putting Device in core would have read as though it were part of the core register set.

client matches how the reference material already describes these implementations when comparing pyharp against Bonsai.Harp.

Notable details

_schema/ flattened into schema/, and _emit_module.py became schema/_module.py. The three test modules that reached into the old harp.device._schema aggregate now name the owning module directly, which is more precise than the aggregate was.

docs/api/device.md had to be rewritten, and mkdocstrings failing on harp.device.Device is what caught it. Sphinx-style cross-references in docstrings were swept as well, since those go stale silently.

test_common_registers_are_not_device_module now asserts against harp.device.core, which is the more precise statement of what it always meant.

harp.device becomes a PEP 420 namespace so a device package can be
harp.device.<name>. The core register set and REGISTER_MAP move to
harp.device.core, the device runtime and transport to
harp.device.client, and the device.yml machinery to harp.device.schema.

Every import of harp.device moves to the portion that owns the name.
@glopesdev
glopesdev requested a review from bruno-f-cruz August 12, 2026 12:05
@glopesdev glopesdev added the feature New planned feature label Aug 12, 2026
@glopesdev
glopesdev merged commit ec2630b into main Aug 12, 2026
13 checks passed
@glopesdev
glopesdev deleted the refactor-device-namespace branch August 12, 2026 14:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature New planned feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants