Home Information - Your home, your data, organized.
Python
Data Import (IMPORT capability)
The IMPORT capability copies upstream items into HI as locally-owned entities. Once imported, the integration has no ongoing relationship with the upstream; HI is the source of truth.
User-facing setup lives in
docs/DataImport.md. This page is the
developer orientation — read the linked modules for the
authoritative API.
Where the code lives
src/hi/integrations/importer/— abstractIntegrationImporterbase, transient models (CandidateItem,IntegrationImportResult,IntegrationDiscardResult), framework-level views (Data Import page, configure, preview, run, discard), templates.src/hi/integrations/view_mixins.py—CapabilityBlockViewMixinfor the cross-capability block-modal detection. Mixed into bothConnectorConfigureViewandImporterConfigureView.src/hi/services/homebox/importer/—HomeBoxImporter, the first concrete implementation. Reference example for new IMPORT-capable integrations.
How a gateway opts in
- Add
IntegrationCapability.IMPORTtoIntegrationMetaData.capabilities. - Override
IntegrationGateway.get_importer()to return a concreteIntegrationImportersubclass.
The IntegrationImporter abstract sits parallel to IntegrationConnector,
not inheriting from it. Commonality between Connect and Import is
composed through shared helpers (HbEntityFactory, HbConverter,
EntityIntegrationOperations, PlacementUrlParams, etc.).
Key design decisions
- Per-entity transaction during
run_import. A single item's failure does not abort the batch; errors are aggregated intoIntegrationImportResult.error_list. See HomeBoxImporter for the pattern. - Skip-by-
integration_name. Imports are add-only. The framework view computes new-vs-skipped against existing HI entities by matchingintegration_name;IntegrationImporter.get_candidate_items()itself returns the full upstream list. - Shared
integrations_syncexclusion lock. Connect-side sync and Import-side run serialize against each other to prevent upstream double-fetch races on a single integration. - State is encoded by the integration columns alone. An entity
is
is_externalwhenintegration_idis set (live Connect),has_integration_provenancewhenprevious_integration_idis set (imported or detached), and neither when native. TheEntityModelManagerexposes named helpers (external_for,imported_for,detached_for,with_integration_provenance) for query sites; the matchingEntityproperties areis_external,is_imported,is_detached, andhas_integration_provenance.
Reference
- HomeBox concrete:
src/hi/services/homebox/importer/ - Tests:
src/hi/integrations/tests/test_importer*.pyandsrc/hi/services/homebox/tests/test_homebox_importer.py. - User-facing:
docs/DataImport.md.