Skip to content

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.py
index 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
@property
def has_changes(self) -> bool:
diff --git a/src/hi/integrations/importer/transient_models.py b/src/hi/integrations/importer/transient_models.py
index 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 = 0
items_skipped_count: int = 0
+ items_filtered_count: int = 0
imported_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 = ''
@property
def has_imports(self) -> bool:
diff --git a/src/hi/services/hass/enums.py b/src/hi/services/hass/enums.py
index 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.py
index 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 the
IntegrationKeys 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_filter
hass_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_filter
hass_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_states
if skipped_count > 0:
+ result.items_filtered_count = skipped_count
result.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.py
index 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:
@classmethod
def 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 = True
else:
allowed_domains = set()
diff --git a/src/hi/services/hass/hass_manager.py b/src/hi/services/hass/hass_manager.py
index 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, ApiHealthStatusPro
return 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_value
def 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.py
index 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 = None
class TestHassConnectorStateConversion(TestCase):
@@ -152,7 +152,7 @@ class TestHassConnectorTransactionBehavior(TestCase):
# Setup manager
mock_manager = Mock()
mock_manager.hass_client = Mock()
- mock_manager.import_allowlist = None
+ mock_manager.include_filter = None
mock_hass_manager.return_value = mock_manager
# Setup scenario: one new device, one entity to remove
@@ -188,7 +188,7 @@ class TestHassConnectorTransactionBehavior(TestCase):
# Setup manager
mock_manager = Mock()
mock_manager.hass_client = Mock()
- mock_manager.import_allowlist = None
+ mock_manager.include_filter = None
mock_hass_manager.return_value = mock_manager
# Setup API data
@@ -233,7 +233,7 @@ class TestHassConnectorErrorScenarios(TestCase):
# Mock manager with client that fails API fetch
mock_manager = Mock()
mock_manager.hass_client = Mock()
- mock_manager.import_allowlist = None
+ mock_manager.include_filter = None
mock_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 mocks
mock_manager = Mock()
mock_manager.hass_client = Mock()
- mock_manager.import_allowlist = None
+ mock_manager.include_filter = None
mock_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 = allowlist
async def fetch_states(verbose=True):
return hass_states_payload
diff --git a/src/hi/services/hass/tests/test_import_allowlist.py b/src/hi/services/hass/tests/test_include_filter.py
similarity index 87%
rename from src/hi/services/hass/tests/test_import_allowlist.py
rename to src/hi/services/hass/tests/test_include_filter.py
index 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 HassConverter
logging.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' } )
return
def 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.py
index 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 IntegrationKey
from hi.services.homebox.connector.hb_external_view_resolver import HomeBoxExternalViewResolver
from hi.services.homebox.hb_controller import HomeBoxController
+from hi.services.homebox.hb_filter_footer import HB_FILTER_FOOTER_MESSAGE
from hi.services.homebox.monitors import HomeBoxMonitor
from hi.services.homebox.hb_converter import HbConverter
from 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 via
timestamps 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 None
summary_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_entities
return result
def _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 (for
the 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 = 0
for 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 += 1
continue
+ if filter_active and not HbConverter.is_item_allowed(
+ hb_item = item,
+ include_tokens = include_tokens,
+ exclude_tokens = exclude_tokens ):
+ skipped_filtered += 1
+ continue
try:
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_MESSAGE
integration_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.py
index 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.py
index 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, Optional
import mimetypes
import os
import 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 )
+
@classmethod
def 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.py
new file mode 100644
index 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.py
index 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, ApiHealthStatus
def 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.py
index 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 IntegrationAttribute
from 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_MESSAGE
from hi.services.homebox.hb_metadata import HbMetaData
from hi.services.homebox.hb_mixins import HomeBoxMixin
+from hi.services.homebox.hb_models import HbItem
from hi.services.homebox.hb_entity_factory import HbEntityFactory
from .hb_importer import populate_attributes_for_imported_entity
@@ -55,11 +58,16 @@ class HomeBoxImporter( IntegrationImporter, HomeBoxMixin ):
"""Lightweight upstream pull for the preview step. Returns the
full upstream item list as ``CandidateItem``s; the framework
decides 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 ):
+ continue
candidates.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
+ continue
integration_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 this
integration_id. Any coexisting active-Connect entities for
diff --git a/src/hi/services/homebox/tests/test_hb_converter.py b/src/hi/services/homebox/tests/test_hb_converter.py
index 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.py
index 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.py
index 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 message
for 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_filter
async def fetch_summary():
return summary_list
diff --git a/src/hi/services/homebox/tests/test_homebox_importer.py b/src/hi/services/homebox/tests/test_homebox_importer.py
index 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 HbItem
logging.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)