Home Information - Your home, your data, organized.
Python
HomeBox connect/import filtering by location and tag (#371) (#372)
Tony Cac99167b2af2
diff --git a/src/hi/integrations/connector/sync_result.py b/src/hi/integrations/connector/sync_result.pyindex 13dfba4a..913ebe60 100644--- a/src/hi/integrations/connector/sync_result.py+++ b/src/hi/integrations/connector/sync_result.py@@ -91,6 +91,7 @@ class IntegrationSyncResult:info_list: List[str] = field(default_factory=list)error_list: List[str] = field(default_factory=list)footer_message: str = ''+ items_filtered_count: int = 0@propertydef has_changes(self) -> bool:diff --git a/src/hi/integrations/importer/transient_models.py b/src/hi/integrations/importer/transient_models.pyindex 3b59c246..c6185390 100644--- a/src/hi/integrations/importer/transient_models.py+++ b/src/hi/integrations/importer/transient_models.py@@ -40,9 +40,11 @@ class IntegrationImportResult:created_entities: List[Entity] = field(default_factory=list)items_imported_count: int = 0items_skipped_count: int = 0+ items_filtered_count: int = 0imported_list: List[str] = field(default_factory=list)info_list: List[str] = field(default_factory=list)error_list: List[str] = field(default_factory=list)+ footer_message: str = ''@propertydef has_imports(self) -> bool:diff --git a/src/hi/services/hass/enums.py b/src/hi/services/hass/enums.pyindex 9f6a89a2..f86bad9a 100644--- a/src/hi/services/hass/enums.py+++ b/src/hi/services/hass/enums.py@@ -29,9 +29,9 @@ class HassAttributeType( IntegrationAttributeType ):False,True,)- IMPORT_ALLOWLIST = (+ INCLUDE_FILTER = ('Allowed Item Types',- 'HA domains and device classes to import (one per line). '+ 'HA domains and device classes to include (one per line). ''Use "domain" for all classes, or "domain:class" for specific ones.',AttributeValueType.TEXT,None,diff --git a/src/hi/services/hass/hass_connector.py b/src/hi/services/hass/hass_connector.pyindex e16a5c55..291beb5d 100644--- a/src/hi/services/hass/hass_connector.py+++ b/src/hi/services/hass/hass_connector.py@@ -83,9 +83,9 @@ class HassConnector( IntegrationConnector, HassMixin ):"""Issue #283 — sync-check probe for Home Assistant.Fetches the same ``/api/states`` payload the periodic monitor- uses, applies the configured Allowed Item Types allowlist (so- the upstream key set matches what Refresh would actually- import — not what HA exposes raw), then compares against the+ uses, applies the configured Allowed Item Types include+ filter (so the upstream key set matches what Refresh would+ actually import — not what HA exposes raw), then compares against theIntegrationKeys of HA-attached HI entities.Convention matched to@@ -102,10 +102,10 @@ class HassConnector( IntegrationConnector, HassMixin ):hass_entity_id_to_state = await hass_manager.fetch_hass_states_from_api_async(verbose = False,)- import_allowlist = hass_manager.import_allowlist+ include_filter = hass_manager.include_filterhass_device_id_to_device = HassConverter.hass_states_to_hass_devices(hass_entity_id_to_state = hass_entity_id_to_state,- import_allowlist = import_allowlist,+ include_filter = include_filter,)upstream_keys = {HassConverter.hass_device_to_integration_key( hass_device )@@ -154,14 +154,14 @@ class HassConnector( IntegrationConnector, HassMixin ):integration_key_to_entity = self._get_existing_hass_entities( result = result )result.info_list.append( f'Found {len(integration_key_to_entity)} existing Home Assistant items.' )- import_allowlist = hass_manager.import_allowlist+ include_filter = hass_manager.include_filterhass_device_id_to_device = HassConverter.hass_states_to_hass_devices(hass_entity_id_to_state = hass_entity_id_to_state,- import_allowlist = import_allowlist,+ include_filter = include_filter,)result.info_list.append( f'Found {len(hass_device_id_to_device)} current Home Assistant devices.' )- if import_allowlist:+ if include_filter:total_states = len( hass_entity_id_to_state )imported_states = sum(len( device.hass_state_list )@@ -169,6 +169,7 @@ class HassConnector( IntegrationConnector, HassMixin ):)skipped_count = total_states - imported_statesif skipped_count > 0:+ result.items_filtered_count = skipped_countresult.info_list.append(f'Filtered {skipped_count} states not matching the Allowed Item Types.')diff --git a/src/hi/services/hass/hass_converter.py b/src/hi/services/hass/hass_converter.pyindex db1bb16d..7bcbc52b 100644--- a/src/hi/services/hass/hass_converter.py+++ b/src/hi/services/hass/hass_converter.py@@ -77,8 +77,9 @@ class HassConverter:"""@staticmethod- def parse_import_allowlist( allowlist_text : str ) -> Tuple[ Set[str], Set[Tuple[str, str]] ]:- """Parse allowlist text into domain-only and domain:class rule sets.+ def parse_include_filter( filter_text : str ) -> Tuple[ Set[str], Set[Tuple[str, str]] ]:+ """Parse the user-supplied include-filter text into+ domain-only and domain:class rule sets.Returns:(allowed_domains, allowed_domain_classes) where:- allowed_domains: set of domains where all classes are allowed@@ -86,7 +87,7 @@ class HassConverter:"""allowed_domains = set()allowed_domain_classes = set()- for line in allowlist_text.strip().splitlines():+ for line in filter_text.strip().splitlines():rule = line.strip()if not rule:continue@@ -418,7 +419,7 @@ class HassConverter:@classmethoddef hass_states_to_hass_devices( cls,hass_entity_id_to_state : Dict[ str, HassState ],- import_allowlist : Optional[str] = None,+ include_filter : Optional[str] = None,) -> Dict[ str, HassDevice ]:"""The Home Assistant (HAss) model we see by fetching the HAss states does@@ -431,8 +432,8 @@ class HassConverter:# When an allowlist is configured, it is the sole authority on what# gets imported. When not configured, fall back to IGNORE_DOMAINS.- if import_allowlist:- allowed_domains, allowed_domain_classes = cls.parse_import_allowlist( import_allowlist )+ if include_filter:+ allowed_domains, allowed_domain_classes = cls.parse_include_filter( include_filter )use_allowlist = Trueelse:allowed_domains = set()diff --git a/src/hi/services/hass/hass_manager.py b/src/hi/services/hass/hass_manager.pyindex 6cc570bd..ee7d9ce3 100644--- a/src/hi/services/hass/hass_manager.py+++ b/src/hi/services/hass/hass_manager.py@@ -202,11 +202,11 @@ class HassManager( SingletonManager, AggregateHealthProvider, ApiHealthStatusProreturn False@property- def import_allowlist( self ) -> str:- attribute = self._hass_attr_type_to_attribute.get( HassAttributeType.IMPORT_ALLOWLIST )+ def include_filter( self ) -> str:+ attribute = self._hass_attr_type_to_attribute.get( HassAttributeType.INCLUDE_FILTER )if attribute and attribute.value:return attribute.value- return HassAttributeType.IMPORT_ALLOWLIST.initial_value+ return HassAttributeType.INCLUDE_FILTER.initial_valuedef fetch_hass_states_from_api( self, verbose : bool = True ) -> Dict[ str, HassState ]:if verbose:diff --git a/src/hi/services/hass/tests/test_hass_connector.py b/src/hi/services/hass/tests/test_hass_connector.pyindex e6ea9b27..4bda3e28 100644--- a/src/hi/services/hass/tests/test_hass_connector.py+++ b/src/hi/services/hass/tests/test_hass_connector.py@@ -92,7 +92,7 @@ class TestHassConnectorSyncHelper(TestCase):self.mock_manager = Mock()self.mock_client = Mock()self.mock_manager.hass_client = self.mock_client- self.mock_manager.import_allowlist = None+ self.mock_manager.include_filter = Noneclass TestHassConnectorStateConversion(TestCase):@@ -152,7 +152,7 @@ class TestHassConnectorTransactionBehavior(TestCase):# Setup managermock_manager = Mock()mock_manager.hass_client = Mock()- mock_manager.import_allowlist = None+ mock_manager.include_filter = Nonemock_hass_manager.return_value = mock_manager# Setup scenario: one new device, one entity to remove@@ -188,7 +188,7 @@ class TestHassConnectorTransactionBehavior(TestCase):# Setup managermock_manager = Mock()mock_manager.hass_client = Mock()- mock_manager.import_allowlist = None+ mock_manager.include_filter = Nonemock_hass_manager.return_value = mock_manager# Setup API data@@ -233,7 +233,7 @@ class TestHassConnectorErrorScenarios(TestCase):# Mock manager with client that fails API fetchmock_manager = Mock()mock_manager.hass_client = Mock()- mock_manager.import_allowlist = None+ mock_manager.include_filter = Nonemock_manager.fetch_hass_states_from_api.side_effect = Exception("API connection failed")mock_hass_manager.return_value = mock_manager@@ -252,7 +252,7 @@ class TestHassConnectorErrorScenarios(TestCase):# Setup mocksmock_manager = Mock()mock_manager.hass_client = Mock()- mock_manager.import_allowlist = None+ mock_manager.include_filter = Nonemock_manager.fetch_hass_states_from_api.return_value = {'test': Mock()}mock_hass_manager.return_value = mock_manager@@ -408,7 +408,7 @@ class TestHassConnectorCheckNeedsSync(AsyncTaskTestCase):def _run_check(self, hass_states_payload, allowlist=''):synchronizer = HassConnector()manager = Mock()- manager.import_allowlist = allowlist+ manager.include_filter = allowlistasync def fetch_states(verbose=True):return hass_states_payloaddiff --git a/src/hi/services/hass/tests/test_import_allowlist.py b/src/hi/services/hass/tests/test_include_filter.pysimilarity index 87%rename from src/hi/services/hass/tests/test_import_allowlist.pyrename to src/hi/services/hass/tests/test_include_filter.pyindex ee5e3d7e..d7d906f4 100644--- a/src/hi/services/hass/tests/test_import_allowlist.py+++ b/src/hi/services/hass/tests/test_include_filter.py@@ -8,11 +8,11 @@ from hi.services.hass.hass_converter import HassConverterlogging.disable( logging.CRITICAL )-class TestParseImportAllowlist( SimpleTestCase ):+class TestParseIncludeFilter( SimpleTestCase ):def test_parse_domain_only_rules( self ):allowlist = 'light\nswitch\nsensor'- domains, domain_classes = HassConverter.parse_import_allowlist( allowlist )+ domains, domain_classes = HassConverter.parse_include_filter( allowlist )self.assertEqual( domains, { 'light', 'switch', 'sensor' } )self.assertEqual( domain_classes, set() )@@ -20,7 +20,7 @@ class TestParseImportAllowlist( SimpleTestCase ):def test_parse_domain_class_rules( self ):allowlist = 'sensor:temperature\nbinary_sensor:motion'- domains, domain_classes = HassConverter.parse_import_allowlist( allowlist )+ domains, domain_classes = HassConverter.parse_include_filter( allowlist )self.assertEqual( domains, set() )self.assertEqual( domain_classes, {@@ -31,7 +31,7 @@ class TestParseImportAllowlist( SimpleTestCase ):def test_parse_mixed_rules( self ):allowlist = 'light\nsensor:temperature\nswitch\nbinary_sensor:door'- domains, domain_classes = HassConverter.parse_import_allowlist( allowlist )+ domains, domain_classes = HassConverter.parse_include_filter( allowlist )self.assertEqual( domains, { 'light', 'switch' } )self.assertEqual( domain_classes, {@@ -42,14 +42,14 @@ class TestParseImportAllowlist( SimpleTestCase ):def test_parse_ignores_blank_lines( self ):allowlist = 'light\n\n\nswitch\n \n'- domains, domain_classes = HassConverter.parse_import_allowlist( allowlist )+ domains, domain_classes = HassConverter.parse_include_filter( allowlist )self.assertEqual( domains, { 'light', 'switch' } )returndef test_parse_strips_whitespace( self ):allowlist = ' light \n sensor:temperature '- domains, domain_classes = HassConverter.parse_import_allowlist( allowlist )+ domains, domain_classes = HassConverter.parse_include_filter( allowlist )self.assertEqual( domains, { 'light' } )self.assertEqual( domain_classes, { ( 'sensor', 'temperature' ) } )diff --git a/src/hi/services/homebox/connector/homebox_connector.py b/src/hi/services/homebox/connector/homebox_connector.pyindex 8b8ef7c8..f21baac2 100644--- a/src/hi/services/homebox/connector/homebox_connector.py+++ b/src/hi/services/homebox/connector/homebox_connector.py@@ -16,6 +16,7 @@ from hi.integrations.transient_models import IntegrationKeyfrom hi.services.homebox.connector.hb_external_view_resolver import HomeBoxExternalViewResolverfrom hi.services.homebox.hb_controller import HomeBoxController+from hi.services.homebox.hb_filter_footer import HB_FILTER_FOOTER_MESSAGEfrom hi.services.homebox.monitors import HomeBoxMonitorfrom hi.services.homebox.hb_converter import HbConverterfrom hi.services.homebox.hb_manager import HomeBoxManager@@ -62,6 +63,11 @@ class HomeBoxConnector( IntegrationConnector, HomeBoxMixin ):item becomes one HI entity whose ``integration_name`` is``str(item.id)``. Adds/removes only — update detection viatimestamps is deferred.++ The include/exclude filter is applied here too so the+ upstream key set matches what the full sync would actually+ keep — otherwise drift detection reports phantom "missing"+ items that the sync would have filtered out anyway."""hb_manager = await self.hb_manager_async()if hb_manager is None:@@ -69,20 +75,29 @@ class HomeBoxConnector( IntegrationConnector, HomeBoxMixin ):# try again. Returning None opts this cycle out cleanly.return Nonesummary_list = await hb_manager.fetch_hb_items_summary_from_api_async()+ include_tokens = HbConverter.parse_filter_list( hb_manager.include_filter )+ exclude_tokens = HbConverter.parse_filter_list( hb_manager.exclude_filter )# ``archived: true`` upstream is HomeBox's "no longer in# active use" marker. Treat archived items as if they were# absent so the sync-check correctly reports them as removed# — see ``_sync_helper_entities`` for the matching filter on# the full-detail fetch.- upstream_keys = {- IntegrationKey(+ upstream_keys = set()+ for item in summary_list:+ if item.get('id') is None:+ continue+ if item.get('archived') is True:+ continue+ if include_tokens or exclude_tokens:+ if not HbConverter.is_item_allowed(+ hb_item = HbItem( api_dict = item ),+ include_tokens = include_tokens,+ exclude_tokens = exclude_tokens ):+ continue+ upstream_keys.add( IntegrationKey(integration_id = HbMetaData.integration_id,integration_name = str( item['id'] ),- )- for item in summary_list- if item.get('id') is not None- and item.get('archived') is not True- }+ ) )current_keys = await sync_to_async( self._get_current_integration_keys )()return IntegrationSyncCheck.compute_delta(upstream_keys = upstream_keys,@@ -132,22 +147,39 @@ class HomeBoxConnector( IntegrationConnector, HomeBoxMixin ):result.info_list.append( f'Found {len(item_list)} current HomeBox items.' )+ include_tokens = HbConverter.parse_filter_list( hb_manager.include_filter )+ exclude_tokens = HbConverter.parse_filter_list( hb_manager.exclude_filter )+# Existing-entity updates do not need re-placement; only# newly-created entities surface in the dispatcher.created_entities = self._sync_helper_entities(- item_list = item_list, result = result )+ item_list = item_list,+ result = result,+ include_tokens = include_tokens,+ exclude_tokens = exclude_tokens,+ )result.created_entities = created_entitiesreturn resultdef _sync_helper_entities( self,item_list: List[HbItem],- result: IntegrationSyncResult ) -> List[Entity]:+ result: IntegrationSyncResult,+ include_tokens = frozenset(),+ exclude_tokens = frozenset() ) -> List[Entity]:"""Sync HomeBox items and return newly-created entities (forthe caller to feed into group_entities_for_placement).Existing-entity updates do not contribute — they don't need- re-placement."""+ re-placement.++ ``include_tokens`` / ``exclude_tokens`` are pre-parsed by the+ caller (``_sync_impl``); filtering is a no-op when both are+ empty, which keeps callers without a configured filter on+ the original code path."""+ filter_active = bool( include_tokens or exclude_tokens )+integration_key_to_item = dict()skipped_archived = 0+ skipped_filtered = 0for item in item_list:# ``archived: true`` upstream means the item is no# longer in active use. Skip it so the sync's removal@@ -159,6 +191,12 @@ class HomeBoxConnector( IntegrationConnector, HomeBoxMixin ):if item.archived is True:skipped_archived += 1continue+ if filter_active and not HbConverter.is_item_allowed(+ hb_item = item,+ include_tokens = include_tokens,+ exclude_tokens = exclude_tokens ):+ skipped_filtered += 1+ continuetry:integration_key = HbConverter.hb_item_to_integration_key( hb_item = item )integration_key_to_item[integration_key] = item@@ -169,6 +207,12 @@ class HomeBoxConnector( IntegrationConnector, HomeBoxMixin ):result.info_list.append(f'Skipped {skipped_archived} archived HomeBox item(s).')+ if skipped_filtered:+ result.items_filtered_count = skipped_filtered+ result.info_list.append(+ f'Filtered {skipped_filtered} item(s) not matching your include/exclude filter.'+ )+ result.footer_message = HB_FILTER_FOOTER_MESSAGEintegration_key_to_entity = self._get_existing_hb_entities( result = result )result.info_list.append( f'Found {len(integration_key_to_entity)} existing HomeBox items.' )diff --git a/src/hi/services/homebox/enums.py b/src/hi/services/homebox/enums.pyindex 5f8bdf8c..36d6ed6e 100644--- a/src/hi/services/homebox/enums.py+++ b/src/hi/services/homebox/enums.py@@ -29,3 +29,19 @@ class HbAttributeType( IntegrationAttributeType ):True,True,)+ INCLUDE_FILTER = (+ 'Include Items By Location/Tag',+ 'One location or tag name per line.',+ AttributeValueType.TEXT,+ None,+ True,+ False,+ )+ EXCLUDE_FILTER = (+ 'Exclude Items By Location/Tag',+ 'One location or tag name per line.',+ AttributeValueType.TEXT,+ None,+ True,+ False,+ )diff --git a/src/hi/services/homebox/hb_converter.py b/src/hi/services/homebox/hb_converter.pyindex 429ad367..23fd6071 100644--- a/src/hi/services/homebox/hb_converter.py+++ b/src/hi/services/homebox/hb_converter.py@@ -1,4 +1,4 @@-from typing import Dict, List, Optional+from typing import Dict, FrozenSet, List, Optionalimport mimetypesimport osimport re@@ -175,6 +175,96 @@ _KEYWORD_PATTERNS = [class HbConverter:+ # Single non-alphanumeric → space; collapsed and stripped.+ # Common delimiters like '-' and '_' fall through this rule+ # naturally — they become spaces, then the collapse step+ # merges runs of spaces. ASCII-only by design; the filter+ # vocabulary is operator-provided text.+ _NORMALIZE_PATTERN = re.compile( r'[^a-z0-9]+' )++ @classmethod+ def _normalize_filter_token( cls, text: str ) -> str:+ """Lower-case, treat any non-alphanumeric run as a+ separator (so ``Garage-2``, ``garage_2`` and ``Garage 2``+ all collapse to ``garage 2``), then collapse and strip+ whitespace."""+ if not text:+ return ''+ return cls._NORMALIZE_PATTERN.sub( ' ', text.lower() ).strip()++ @classmethod+ def parse_filter_list( cls, filter_text: str ) -> FrozenSet[ str ]:+ """Parse the multiline operator-supplied include/exclude+ filter into a normalized set of tokens. Empty / whitespace+ lines silently skipped. Tokens that normalize to the empty+ string are dropped."""+ if not filter_text:+ return frozenset()+ tokens = set()+ for line in filter_text.splitlines():+ token = cls._normalize_filter_token( line )+ if token:+ tokens.add( token )+ return frozenset( tokens )++ @classmethod+ def is_item_allowed( cls,+ hb_item : HbItem,+ include_tokens : FrozenSet[ str ],+ exclude_tokens : FrozenSet[ str ],+ ) -> bool:+ """Apply the include + exclude filter to a single HomeBox+ item. Match is against the item's location name and any tag+ name, all normalized via ``_normalize_filter_token``.++ Precedence (per issue #371):+ - Both filters empty → admit.+ - Include set, item matches any token → survives the+ include stage. Exclude then removes it if any item+ token matches the exclude list.+ - Include set, item matches no token → rejected.+ (Orphans with no location and no tags fall here.)+ - Include empty, exclude set → admit unless excluded.+ """+ item_tokens = cls._collect_item_tokens( hb_item = hb_item )++ if include_tokens:+ if not item_tokens.intersection( include_tokens ):+ return False++ if exclude_tokens and item_tokens.intersection( exclude_tokens ):+ return False++ return True++ @classmethod+ def _collect_item_tokens( cls, hb_item: HbItem ) -> FrozenSet[ str ]:+ """Return the normalized comparison tokens for an item:+ its location name (if any) plus each tag name."""+ tokens = set()++ location = hb_item.location+ if isinstance( location, dict ):+ location_name = location.get( 'name' )+ if location_name:+ normalized = cls._normalize_filter_token( location_name )+ if normalized:+ tokens.add( normalized )++ tags = hb_item.tags+ if isinstance( tags, list ):+ for tag in tags:+ if not isinstance( tag, dict ):+ continue+ tag_name = tag.get( 'name' )+ if not tag_name:+ continue+ normalized = cls._normalize_filter_token( tag_name )+ if normalized:+ tokens.add( normalized )++ return frozenset( tokens )+@classmethoddef hb_item_to_integration_key( cls, hb_item: HbItem ) -> IntegrationKey:return IntegrationKey(diff --git a/src/hi/services/homebox/hb_filter_footer.py b/src/hi/services/homebox/hb_filter_footer.pynew file mode 100644index 00000000..62bfa923--- /dev/null+++ b/src/hi/services/homebox/hb_filter_footer.py@@ -0,0 +1,13 @@+"""+Footer message shown on connect/import results when the HomeBox+include/exclude filter removed any items. Centralized so the+connector and importer paths surface identical guidance to the+operator.+"""++HB_FILTER_FOOTER_MESSAGE = (+ 'Not seeing all your HomeBox items? Check the '+ '"Include Items By Location/Tag" and '+ '"Exclude Items By Location/Tag" in the HomeBox '+ 'integration settings.'+)diff --git a/src/hi/services/homebox/hb_manager.py b/src/hi/services/homebox/hb_manager.pyindex aa65ffa4..dc9afa79 100644--- a/src/hi/services/homebox/hb_manager.py+++ b/src/hi/services/homebox/hb_manager.py@@ -87,6 +87,20 @@ class HomeBoxManager( SingletonManager, AggregateHealthProvider, ApiHealthStatusdef hb_client(self) -> HbClient:return self._hb_client+ @property+ def include_filter( self ) -> str:+ attribute = self._hb_attr_type_to_attribute.get( HbAttributeType.INCLUDE_FILTER )+ if attribute and attribute.value:+ return attribute.value+ return ''++ @property+ def exclude_filter( self ) -> str:+ attribute = self._hb_attr_type_to_attribute.get( HbAttributeType.EXCLUDE_FILTER )+ if attribute and attribute.value:+ return attribute.value+ return ''+def _reload_implementation( self ):try:self._hb_attr_type_to_attribute = self._load_attributes()diff --git a/src/hi/services/homebox/importer/homebox_importer.py b/src/hi/services/homebox/importer/homebox_importer.pyindex 4fb6454f..96b51b45 100644--- a/src/hi/services/homebox/importer/homebox_importer.py+++ b/src/hi/services/homebox/importer/homebox_importer.py@@ -29,8 +29,11 @@ from hi.integrations.importer.transient_models import (from hi.integrations.models import IntegrationAttributefrom hi.integrations.transient_models import IntegrationMetaData, IntegrationValidationResult+from hi.services.homebox.hb_converter import HbConverter+from hi.services.homebox.hb_filter_footer import HB_FILTER_FOOTER_MESSAGEfrom hi.services.homebox.hb_metadata import HbMetaDatafrom hi.services.homebox.hb_mixins import HomeBoxMixin+from hi.services.homebox.hb_models import HbItemfrom hi.services.homebox.hb_entity_factory import HbEntityFactoryfrom .hb_importer import populate_attributes_for_imported_entity@@ -55,11 +58,16 @@ class HomeBoxImporter( IntegrationImporter, HomeBoxMixin ):"""Lightweight upstream pull for the preview step. Returns thefull upstream item list as ``CandidateItem``s; the frameworkdecides which are new vs. already-imported by comparing- ``integration_name`` against existing HI entities."""+ ``integration_name`` against existing HI entities. The+ include/exclude filter is applied here so the preview count+ matches what ``run_import`` will actually pull."""hb_manager = self.hb_manager()if not hb_manager.hb_client:return []summary_list = hb_manager.fetch_hb_items_summary_from_api()+ include_tokens = HbConverter.parse_filter_list( hb_manager.include_filter )+ exclude_tokens = HbConverter.parse_filter_list( hb_manager.exclude_filter )+ filter_active = bool( include_tokens or exclude_tokens )candidates: List[CandidateItem] = []for summary in summary_list:item_id = summary.get( 'id' )@@ -70,6 +78,11 @@ class HomeBoxImporter( IntegrationImporter, HomeBoxMixin ):# so imports don't pull HomeBox's tombstones.if summary.get( 'archived' ) is True:continue+ if filter_active and not HbConverter.is_item_allowed(+ hb_item = HbItem( api_dict = summary ),+ include_tokens = include_tokens,+ exclude_tokens = exclude_tokens ):+ continuecandidates.append( CandidateItem(name = summary.get( 'name' ) or f'HomeBox Item {item_id}',integration_name = str( item_id ),@@ -110,10 +123,20 @@ class HomeBoxImporter( IntegrationImporter, HomeBoxMixin ):).values_list( 'previous_integration_name', flat = True ))+ include_tokens = HbConverter.parse_filter_list( hb_manager.include_filter )+ exclude_tokens = HbConverter.parse_filter_list( hb_manager.exclude_filter )+ filter_active = bool( include_tokens or exclude_tokens )+created_entities = []for hb_item in item_list:if hb_item.archived is True:continue+ if filter_active and not HbConverter.is_item_allowed(+ hb_item = hb_item,+ include_tokens = include_tokens,+ exclude_tokens = exclude_tokens ):+ result.items_filtered_count += 1+ continueintegration_name = str( hb_item.id )if integration_name in existing_integration_names:result.items_skipped_count += 1@@ -142,6 +165,12 @@ class HomeBoxImporter( IntegrationImporter, HomeBoxMixin ):result.created_entities = created_entities+ if result.items_filtered_count > 0:+ result.info_list.append(+ f'Filtered {result.items_filtered_count} item(s) not matching your include/exclude filter.'+ )+ result.footer_message = HB_FILTER_FOOTER_MESSAGE+def discard_imported_data( self, integration_id: str ) -> IntegrationDiscardResult:"""Remove all entities previously imported under thisintegration_id. Any coexisting active-Connect entities fordiff --git a/src/hi/services/homebox/tests/test_hb_converter.py b/src/hi/services/homebox/tests/test_hb_converter.pyindex 8fbc8777..cbaa6cbc 100644--- a/src/hi/services/homebox/tests/test_hb_converter.py+++ b/src/hi/services/homebox/tests/test_hb_converter.py@@ -344,3 +344,153 @@ class TestHbItemToEntityType(TestCase):)),EntityType.CAMERA,)+++def _item_with(location_name=None, tag_names=None, item_id='item-1', name='X'):+ """Build a stub HbItem with the given location / tag names.+ The filter predicate only reads ``location`` and ``tags`` from+ the api_dict, so the other fields can stay minimal."""+ api_dict = {+ 'id': item_id,+ 'name': name,+ 'tags': (+ [{'name': tag} for tag in tag_names]+ if tag_names is not None else []+ ),+ }+ if location_name is not None:+ api_dict['location'] = {'name': location_name}+ return HbItem(api_dict=api_dict, client=Mock())+++class TestHbConverterFilterNormalization(TestCase):+ """Aggressive normalization is the entire reason the filter UX+ can be a plain list of names. Pin the rule so a careless+ refactor doesn't accidentally make the match strict."""++ def test_case_folded(self):+ self.assertEqual(HbConverter._normalize_filter_token('Garage'), 'garage')++ def test_outer_whitespace_trimmed(self):+ self.assertEqual(HbConverter._normalize_filter_token(' garage '), 'garage')++ def test_hyphen_underscore_treated_as_separator(self):+ self.assertEqual(HbConverter._normalize_filter_token('Garage-Shelf_B'), 'garage shelf b')++ def test_punctuation_stripped(self):+ self.assertEqual(HbConverter._normalize_filter_token("John's Office!"), 'john s office')++ def test_collapsed_whitespace_between_tokens(self):+ self.assertEqual(HbConverter._normalize_filter_token('Garage Shelf'), 'garage shelf')++ def test_empty_input_returns_empty(self):+ self.assertEqual(HbConverter._normalize_filter_token(''), '')+ self.assertEqual(HbConverter._normalize_filter_token(' '), '')+++class TestHbConverterParseFilterList(TestCase):++ def test_empty_text_yields_empty_set(self):+ self.assertEqual(HbConverter.parse_filter_list(''), frozenset())++ def test_one_per_line(self):+ result = HbConverter.parse_filter_list('Garage\nOffice\nKitchen')+ self.assertEqual(result, frozenset({'garage', 'office', 'kitchen'}))++ def test_blank_and_whitespace_lines_ignored(self):+ result = HbConverter.parse_filter_list('Garage\n\n \nOffice\n')+ self.assertEqual(result, frozenset({'garage', 'office'}))++ def test_normalization_dedups_equivalent_tokens(self):+ # "Garage-Shelf" and "garage shelf" normalize identically;+ # the set carries only the normalized form.+ result = HbConverter.parse_filter_list('Garage-Shelf\ngarage shelf\nGARAGE_SHELF')+ self.assertEqual(result, frozenset({'garage shelf'}))+++class TestHbConverterIsItemAllowed(TestCase):+ """End-to-end semantics of the include/exclude predicate.+ Both filters empty → admit; include set requires a positive+ match; exclude wins after the include stage; orphans rejected+ when an include filter is present."""++ EMPTY = frozenset()++ def test_no_filters_admits_everything(self):+ item = _item_with(location_name='Garage', tag_names=['tools'])+ self.assertTrue(HbConverter.is_item_allowed(+ hb_item=item, include_tokens=self.EMPTY, exclude_tokens=self.EMPTY,+ ))++ def test_include_matches_location(self):+ item = _item_with(location_name='Garage', tag_names=[])+ self.assertTrue(HbConverter.is_item_allowed(+ hb_item=item,+ include_tokens=frozenset({'garage'}),+ exclude_tokens=self.EMPTY,+ ))++ def test_include_matches_tag(self):+ item = _item_with(location_name='Storage', tag_names=['power-tools'])+ self.assertTrue(HbConverter.is_item_allowed(+ hb_item=item,+ include_tokens=frozenset({'power tools'}),+ exclude_tokens=self.EMPTY,+ ))++ def test_include_set_but_no_match_rejects(self):+ item = _item_with(location_name='Basement', tag_names=['junk'])+ self.assertFalse(HbConverter.is_item_allowed(+ hb_item=item,+ include_tokens=frozenset({'garage', 'office'}),+ exclude_tokens=self.EMPTY,+ ))++ def test_exclude_removes_matching_item(self):+ item = _item_with(location_name='Garage', tag_names=['tools', 'archive'])+ self.assertFalse(HbConverter.is_item_allowed(+ hb_item=item,+ include_tokens=self.EMPTY,+ exclude_tokens=frozenset({'archive'}),+ ))++ def test_exclude_takes_precedence_over_include(self):+ # Item matches include (tag 'tools') but also matches exclude+ # (tag 'archive') — exclude wins.+ item = _item_with(location_name='Garage', tag_names=['tools', 'archive'])+ self.assertFalse(HbConverter.is_item_allowed(+ hb_item=item,+ include_tokens=frozenset({'tools'}),+ exclude_tokens=frozenset({'archive'}),+ ))++ def test_orphan_rejected_when_include_set(self):+ # Items with no location and no tags can't match any include+ # token, so an active include filter rejects them.+ item = _item_with(location_name=None, tag_names=[])+ self.assertFalse(HbConverter.is_item_allowed(+ hb_item=item,+ include_tokens=frozenset({'garage'}),+ exclude_tokens=self.EMPTY,+ ))++ def test_orphan_admitted_when_only_exclude_set(self):+ # No include, so orphans aren't subject to the+ # "must positively match" rule. Exclude doesn't apply since+ # the item carries no tokens to match.+ item = _item_with(location_name=None, tag_names=[])+ self.assertTrue(HbConverter.is_item_allowed(+ hb_item=item,+ include_tokens=self.EMPTY,+ exclude_tokens=frozenset({'archive'}),+ ))++ def test_match_is_normalization_insensitive(self):+ # The include token is normalized; the item's location is+ # normalized; the comparison sees both as 'garage shelf b'.+ item = _item_with(location_name='Garage-Shelf_B', tag_names=[])+ self.assertTrue(HbConverter.is_item_allowed(+ hb_item=item,+ include_tokens=HbConverter.parse_filter_list('garage shelf b'),+ exclude_tokens=self.EMPTY,+ ))diff --git a/src/hi/services/homebox/tests/test_hb_manager.py b/src/hi/services/homebox/tests/test_hb_manager.pyindex 218e41cf..4e920eb5 100644--- a/src/hi/services/homebox/tests/test_hb_manager.py+++ b/src/hi/services/homebox/tests/test_hb_manager.py@@ -41,7 +41,8 @@ class TestHomeBoxManagerAttributeMap(SimpleTestCase):enforce_requirements=True,)- self.assertEqual(set(result.keys()), set(HbAttributeType))+ required_types = { t for t in HbAttributeType if t.is_required }+ self.assertEqual(set(result.keys()), required_types)def test_build_map_raises_when_required_attribute_missing_and_enforced(self):attrs = [diff --git a/src/hi/services/homebox/tests/test_homebox_connector.py b/src/hi/services/homebox/tests/test_homebox_connector.pyindex 108e8fa6..dd21bf07 100644--- a/src/hi/services/homebox/tests/test_homebox_connector.py+++ b/src/hi/services/homebox/tests/test_homebox_connector.py@@ -28,6 +28,8 @@ class TestHomeBoxConnector(SimpleTestCase):synchronizer = HomeBoxConnector()manager = Mock()manager.hb_client = object()+ manager.include_filter = ''+ manager.exclude_filter = ''manager.fetch_hb_items_from_api.return_value = [Mock(), Mock(), Mock()]with patch.object(synchronizer, 'hb_manager', return_value=manager), \@@ -39,6 +41,8 @@ class TestHomeBoxConnector(SimpleTestCase):sync_entities_mock.assert_called_once_with(item_list=manager.fetch_hb_items_from_api.return_value,result=result,+ include_tokens=frozenset(),+ exclude_tokens=frozenset(),)def test_sync_helper_entities_create_update_remove_entities(self):@@ -130,6 +134,56 @@ class TestHomeBoxConnector(SimpleTestCase):self.assertTrue(any('Ignoring HomeBox item due to missing/invalid id' in messagefor message in result.error_list))+ def test_sync_helper_filters_items_and_populates_count(self):+ """When include/exclude tokens are present, ``_sync_helper_entities``+ rejects non-matching items, increments ``items_filtered_count``+ on the result, and sets the standard footer message."""+ synchronizer = HomeBoxConnector()+ result = IntegrationSyncResult(title='X')++ # Build minimal HbItem-like mocks: only the fields the+ # predicate reads + the archived/id used by the helper.+ from hi.services.homebox.hb_models import HbItem+ item_in = HbItem(api_dict={+ 'id': '1',+ 'name': 'In',+ 'location': {'name': 'Garage'},+ 'tags': [],+ })+ item_out = HbItem(api_dict={+ 'id': '2',+ 'name': 'Out',+ 'location': {'name': 'Basement'},+ 'tags': [],+ })++ with ExitStack() as stack:+ stack.enter_context(patch(+ 'hi.services.homebox.connector.homebox_connector.transaction.atomic',+ return_value=nullcontext(),+ ))+ stack.enter_context(patch.object(+ synchronizer, '_get_existing_hb_entities', return_value={},+ ))+ stack.enter_context(patch.object(+ synchronizer, 'reconnect_disconnected_items',+ ))+ stack.enter_context(patch.object(+ synchronizer, '_create_entity', return_value=Mock(),+ ))++ synchronizer._sync_helper_entities(+ item_list=[item_in, item_out],+ result=result,+ include_tokens=frozenset({'garage'}),+ exclude_tokens=frozenset(),+ )++ self.assertEqual(result.items_filtered_count, 1)+ self.assertTrue(any('Filtered 1 item(s)' in message+ for message in result.info_list))+ self.assertIn('Include Items By Location/Tag', result.footer_message)+class TestHomeBoxConnectorSyncImplCreatedEntities(SimpleTestCase):"""HomeBoxConnector._sync_impl reports newly-created entities@@ -142,6 +196,8 @@ class TestHomeBoxConnectorSyncImplCreatedEntities(SimpleTestCase):synchronizer = HomeBoxConnector()manager = Mock()manager.hb_client = object()+ manager.include_filter = ''+ manager.exclude_filter = ''manager.fetch_hb_items_from_api.return_value = [Mock(), Mock()]entity_a = Mock()@@ -172,6 +228,8 @@ class TestHomeBoxConnectorSyncImplCreatedEntities(SimpleTestCase):synchronizer = HomeBoxConnector()manager = Mock()manager.hb_client = object()+ manager.include_filter = ''+ manager.exclude_filter = ''manager.fetch_hb_items_from_api.return_value = []with patch.object(synchronizer, 'hb_manager', return_value=manager), \@@ -251,9 +309,11 @@ class TestHomeBoxConnectorCheckNeedsSync(AsyncTaskTestCase):integration_name=name,)- def _run_check(self, summary_list):+ def _run_check(self, summary_list, include_filter='', exclude_filter=''):synchronizer = HomeBoxConnector()manager = Mock()+ manager.include_filter = include_filter+ manager.exclude_filter = exclude_filterasync def fetch_summary():return summary_listdiff --git a/src/hi/services/homebox/tests/test_homebox_importer.py b/src/hi/services/homebox/tests/test_homebox_importer.pyindex 265f3b27..feae0a3a 100644--- a/src/hi/services/homebox/tests/test_homebox_importer.py+++ b/src/hi/services/homebox/tests/test_homebox_importer.py@@ -14,14 +14,14 @@ from hi.services.homebox.hb_models import HbItemlogging.disable(logging.CRITICAL)-def _hb_item(item_id, name='Item', archived=False):+def _hb_item(item_id, name='Item', archived=False, location_name='Garage', tag_names=None):return HbItem(api_dict={'id': item_id,'name': name,'archived': archived,- 'location': {'id': 'loc-1', 'name': 'Garage'},- 'tags': [],+ 'location': {'id': 'loc-1', 'name': location_name} if location_name else None,+ 'tags': [{'name': t} for t in (tag_names or [])],'fields': [],'attachments': [],},@@ -35,6 +35,8 @@ class TestHomeBoxImporterGetCandidateItems(TestCase):importer = HomeBoxImporter()mock_manager = Mock()mock_manager.hb_client = Mock()+ mock_manager.include_filter = ''+ mock_manager.exclude_filter = ''mock_manager.fetch_hb_items_summary_from_api.return_value = [{'id': 'item-1', 'name': 'Hammer', 'archived': False},{'id': 'item-2', 'name': 'Saw', 'archived': True},@@ -70,6 +72,8 @@ class TestHomeBoxImporterRunImport(TestCase):importer = HomeBoxImporter()mock_manager = Mock()mock_manager.hb_client = Mock()+ mock_manager.include_filter = ''+ mock_manager.exclude_filter = ''mock_manager.fetch_hb_items_from_api.return_value = [_hb_item('item-1', 'Should skip'),_hb_item('item-2', 'Should import'),@@ -90,6 +94,8 @@ class TestHomeBoxImporterRunImport(TestCase):importer = HomeBoxImporter()mock_manager = Mock()mock_manager.hb_client = Mock()+ mock_manager.include_filter = ''+ mock_manager.exclude_filter = ''mock_manager.fetch_hb_items_from_api.return_value = [_hb_item('item-a', 'Item A'),_hb_item('item-b', 'Item B'),@@ -146,3 +152,46 @@ class TestHomeBoxImporterDiscard(TestCase):result = importer.discard_imported_data(integration_id=HbMetaData.integration_id)self.assertEqual(result.count, 0)self.assertEqual(result.errors, [])+++class TestHomeBoxImporterFilter(TestCase):+ """End-to-end coverage of the include/exclude filter on the+ importer paths — preview (candidate items) and the import+ itself."""++ def test_get_candidate_items_honors_include_filter(self):+ importer = HomeBoxImporter()+ mock_manager = Mock()+ mock_manager.hb_client = Mock()+ mock_manager.include_filter = 'Garage'+ mock_manager.exclude_filter = ''+ mock_manager.fetch_hb_items_summary_from_api.return_value = [+ {'id': '1', 'name': 'A', 'location': {'name': 'Garage'}, 'tags': []},+ {'id': '2', 'name': 'B', 'location': {'name': 'Basement'}, 'tags': []},+ ]+ with patch.object(HomeBoxImporter, 'hb_manager', return_value=mock_manager):+ candidates = importer.get_candidate_items()++ self.assertEqual(len(candidates), 1)+ self.assertEqual(candidates[0].integration_name, '1')++ def test_run_import_filters_and_populates_count(self):+ importer = HomeBoxImporter()+ mock_manager = Mock()+ mock_manager.hb_client = Mock()+ mock_manager.include_filter = 'Garage'+ mock_manager.exclude_filter = ''+ mock_manager.fetch_hb_items_from_api.return_value = [+ _hb_item('item-1', location_name='Garage'),+ _hb_item('item-2', location_name='Basement'),+ _hb_item('item-3', location_name='Garage'),+ ]+ with patch.object(HomeBoxImporter, 'hb_manager', return_value=mock_manager):+ result = importer.run_import()++ # 2 items in Garage imported; 1 in Basement filtered out.+ self.assertEqual(result.items_imported_count, 2)+ self.assertEqual(result.items_filtered_count, 1)+ self.assertTrue(any('Filtered 1 item(s)' in message+ for message in result.info_list))+ self.assertIn('Include Items By Location/Tag', result.footer_message)