@camstack/addon-waste-collections 0.0.0-stage → 0.1.1

package/python/vendor/waste_collection_schedule/source/ecoharmonogram_pl.py

@@ -0,0 +1,688 @@
+import datetime
+import logging
+import re
+from typing import ClassVar, cast
+
+from ..collection import Collection
+from ..exceptions import (
+    SourceArgumentNotFound,
+    SourceArgumentNotFoundWithSuggestions,
+    SourceArgumentRequired,
+    SourceArgumentRequiredWithSuggestions,
+)
+from ..service.EcoHarmonogramPL import (
+    SUPPORTED_APPS_LITERAL,
+    SUPPORTED_LANGUAGES_LITERAL,
+    Ecoharmonogram,
+    Schedule,
+    ScheduleDescription,
+    SchedulePeriod,
+    ScheduleResponse,
+    Street,
+    StreetResponse,
+    Town,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+HOW_TO_GET_ARGUMENTS_DESCRIPTION = {
+    "en": "Fill in Town, Street, Housenumber and District and press confirm. If any other field is required, it will tell you with a dropdown menu of suggestions. If your Town is not found, you might need to provide the App argument. (take a look in the linked documentation below, there is a list of towns with their corresponding App argument)",
+    # "pl": "Wypełnij pola Miasto, Ulica, Numer domu i Dzielnica i naciśnij potwierdź. Jeśli wymagane jest inne pole, zostanie to powiedziane z rozwijanym menu sugestii. Jeśli Twoje miasto nie zostanie znalezione, być może będziesz musiał podać argument App. (zobacz w poniższej dokumentacji, jest lista miast z odpowiadającymi im argumentami App)",
+}
+
+GROUP_DESCRIPTION_EN = "Select Collection group to limit results to a specific group within a waste type (e.g. 'Papier (1 x miesiąc)' for Paper collected once a month). Leave empty and only fill if it fails, you'll then see a list of available groups."
+GROUP_DESCRIPTION_PL = "Wybierz grupę zbiórki, aby ograniczyć wyniki do konkretnej grupy w obrębie typu odpadów (np. 'Papier (1 x miesiąc)' dla papieru zbieranego raz w miesiącu). Pozostaw puste i wypełnij tylko wtedy, gdy wystąpi błąd, wtedy zobaczysz listę dostępnych grup."
+
+PARAM_TRANSLATIONS = {
+    "en": {
+        "town": "Town",
+        "street": "Street",
+        "house_number": "House number",
+        "district": "District",
+        "language": "Language",
+        "additional_sides_matcher": "Additional Sides Matcher",
+        "region": "Region",
+        "community": "Community",
+        "g1": "Group 1",
+        "g2": "Group 2",
+        "g3": "Group 3",
+        "g4": "Group 4",
+        "g5": "Group 5",
+    },
+    # "pl": {
+    #     "town": "Miasto",
+    #     "street": "Ulica",
+    #     "house_number": "Numer domu",
+    #     "district": "Dzielnica",
+    #     "additional_sides_matcher": "Matcher dodatkowych stron zbiórki",
+    #     "region": "Region",
+    #     "community": "Społeczność",
+    #     "g1": "Grupa 1",
+    #     "g2": "Grupa 2",
+    #     "g3": "Grupa 3",
+    #     "g4": "Grupa 4",
+    #     "g5": "Grupa 5",
+    # },
+}
+PARAM_DESCRIPTIONS = {
+    "en": {
+        "town": "Town",
+        "street": "Street",
+        "house_number": "House number",
+        "district": "District",
+        "language": "Language for waste type names (pl, en, uk, ru)",
+        "additional_sides_matcher": "Additional matcher for collection sides. Also used to pick between single-family ('Zabudowa jednorodzinna') and multi-family ('Zabudowa wielorodzinna') schedules for streets that offer both.",
+        "region": "Sub-region within the town used to disambiguate streets that appear in multiple collection areas (e.g. 'Nowy Ramiszów' vs the rest of Ramiszów). Leave empty unless you get an error asking for it — a list of valid options will be shown.",
+        "community": "Community",
+        "g1": GROUP_DESCRIPTION_EN,
+        "g2": GROUP_DESCRIPTION_EN,
+        "g3": GROUP_DESCRIPTION_EN,
+        "g4": GROUP_DESCRIPTION_EN,
+        "g5": GROUP_DESCRIPTION_EN,
+    },
+    # "pl": {
+    #     "town": "Miasto",
+    #     "street": "Ulica",
+    #     "house_number": "Numer domu",
+    #     "district": "Dzielnica",
+    #     "additional_sides_matcher": "Dodatkowy matcher dla stron zbiórki",
+    #     "region": "Podregion w obrębie miasta, używany do rozróżnienia ulic występujących w kilku obszarach zbiórki (np. 'Nowy Ramiszów' vs reszta Ramiszowa). Pozostaw puste, chyba że pojawi się błąd wymagający tego pola — lista dostępnych opcji zostanie wyświetlona.",
+    #     "community": "Społeczność",
+    #     "g1": GROUP_DESCRIPTION_PL,
+    #     "g2": GROUP_DESCRIPTION_PL,
+    #     "g3": GROUP_DESCRIPTION_PL,
+    #     "g4": GROUP_DESCRIPTION_PL,
+    #     "g5": GROUP_DESCRIPTION_PL,
+    # },
+}
+
+
+# {"schedulePeriods":[{"id":"7059","startDate":"2025-01-01","endDate":"2025-03-31","changeDate":"2024-12-19 23:05:18"},{"id":"7946","startDate":"2025-04-01","endDate":"2025-10-31","changeDate":"2025-05-07 09:42:53"}]}
+
+TITLE = "Ecoharmonogram"
+DESCRIPTION = "Source for ecoharmonogram.pl"
+URL = "https://ecoharmonogram.pl"
+TEST_CASES = {
+    "Częstochowa Częstochowa Bartnicza 9": {
+        "town": "Częstochowa",
+        "street": "Bartnicza",
+        "house_number": "9",
+        "district": "Częstochowa",
+        "additional_sides_matcher": "Szkło (1 x miesiąc)",
+        "g1": "Firmy (5 fakcji + popiół 2,3,4 x mc)",
+        "g2": "Zmieszane (5 x miesiąc)",
+        "g3": "Bio (3 x miesiąc)",
+        "g4": "Metale i Tworzywa (4 x miesiąc)",
+        "g5": "Papier (1 x miesiąc)",
+    },
+    "Simple test case": {
+        "town": "Krzeszowice",
+        "street": "Wyki",
+        "house_number": "1",
+        "additional_sides_matcher": "Zabudowa jednorodzinna",
+    },
+    "Sides multi test case": {
+        "town": "Częstochowa",
+        "house_number": "1",
+        "street": "Boczna",
+        "g1": "Firmy (5 frakcji)",
+        "g2": "Zmieszane (5 x miesiąc)",
+        "g3": "Bio (3 x miesiąc)",
+        "g4": "Metale i Tworzywa (2 x miesiąc)",
+        "g5": "Papier (4 x miesiąc)",
+        "additional_sides_matcher": "Szkło (4 x miesiąc)",
+    },
+    "Sides test case": {
+        "town": "Częstochowa",
+        "street": "Azaliowa",
+        "house_number": "1",
+        "g1": "Zabudowa jednorodzinna",
+        "additional_sides_matcher": "jedn",
+    },
+    "Sides multi test case with district": {
+        "town": "Borkowo",
+        "district": "Pruszcz Gdański",
+        "street": "Sadowa",
+        "house_number": "1",
+        "additional_sides_matcher": "Wielorodzinna - powyżej 7 lokali",
+    },
+    "Simple test with community": {
+        "town": "Gdańsk",
+        "street": "Jabłoniowa",
+        "house_number": "55",
+        "g1": "Zabudowa jednorodzinna",
+        "additional_sides_matcher": "",
+        # "app": "gdansk",
+        "community": "108",
+    },
+    "Zawiercie, Równa, Zawiercie": {
+        "town": "Zawiercie",
+        "street": "Równa",
+        "house_number": "1",
+        "district": "Zawiercie",
+    },
+    "Case for multi id separated with comma (single-family)": {
+        "town": "Zabrze",
+        "street": "Leśna",
+        "district": "Zabrze",
+        "house_number": "1",
+        "additional_sides_matcher": "Zabudowa jednorodzinna",
+    },
+    "Case for multi id separated with comma (multi-family)": {
+        "town": "Zabrze",
+        "street": "Leśna",
+        "district": "Zabrze",
+        "house_number": "1",
+        "additional_sides_matcher": "Zabudowa wielorodzinna",
+    },
+    "Case for multiple schedules for the same house": {
+        "town": "Nadolice Wielkie",
+        "street": "Zbożowa",
+        "district": "Czernica",
+        "g1": "tylko odpady zmieszane",
+        "house_number": "1",
+    },
+    "With app": {
+        "town": "Buczków",
+        "street": "Buczków",
+        "house_number": "1",
+        "app": "eco-przyszlosc",
+        "additional_sides_matcher": "Zabudowa wielolokalowa i niezamieszkała o zwiększonej częstotliwości",
+    },
+    "Rzeszów, Krakowska 317E (individual customers, range match numberFrom=16)": {
+        "town": "Rzeszów",
+        "community": "60",
+        "street": "Krakowska",
+        "house_number": "317E",
+        "g1": "Klienci indywidualni",
+        "additional_sides_matcher": "Klienci indywidualni",
+    },
+    "Ukrainian language": {
+        "town": "Krzeszowice",
+        "street": "Wyki",
+        "house_number": "1",
+        "additional_sides_matcher": "Заміська забудова",
+        "language": "uk",
+    },
+    "Sławków (mixed sides: empty + non-empty, no matcher)": {
+        "town": "Sławków",
+        "street": "Jagiellońska",
+        "house_number": "32",
+        "additional_sides_matcher": "",  # Available sides are "Zabudowa wysoka" and "" (empty string)
+    },
+    "Tarnowskie Góry, Gliwicka 1": {
+        "town": "Tarnowskie Góry",
+        "street": "Gliwicka",
+        "house_number": "1",
+        "additional_sides_matcher": "Zabudowa jednorodzinna",
+    },
+    "Wodzisław Śląski, Mszańska 16 (community 23)": {
+        "town": "Wodzisław Śląski",
+        "district": "Wodzisław Śląski",
+        "community": "23",
+        "street": "Mszańska",
+        "house_number": "16",
+    },
+    "Ramiszów (region Nowy Ramiszów)": {
+        "town": "Ramiszów",
+        "house_number": "200",
+        "additional_sides_matcher": "Zabudowa jednorodzinna",
+        "region": "Nowy Ramiszów",
+    },
+}
+
+
+class ScheduleWithName(Schedule):
+    name: str
+
+
+class Source:
+    def __init__(
+        self,
+        town,
+        app: SUPPORTED_APPS_LITERAL = None,
+        language: SUPPORTED_LANGUAGES_LITERAL = "pl",
+        district="",
+        street="",
+        house_number="",
+        additional_sides_matcher="",
+        region="",
+        community="",
+        g1="",
+        g2="",
+        g3="",
+        g4="",
+        g5="",
+    ):
+        self.town_input = town
+        self.street_input = street
+        self.house_number_input = house_number
+        self.district_input = district
+        self.additional_sides_matcher_input = additional_sides_matcher
+        self.region_input = region
+        self.community_input = community
+        self._g1 = g1
+        self._g2 = g2
+        self._g3 = g3
+        self._g4 = g4
+        self._g5 = g5
+
+        # house_number should be required as group matching requires it and the App enforces it too, Keeping it as optional for now to show a better error message
+        if not house_number:
+            raise SourceArgumentRequired(
+                "house_number",
+                "House number is required for Ecoharmonogram source.",
+            )
+
+        self._groups = {
+            "g1": self._g1,
+            "g2": self._g2,
+            "g3": self._g3,
+            "g4": self._g4,
+            "g5": self._g5,
+        }
+
+        self._ecoharmonogram_pl = Ecoharmonogram(app=app, language=language)
+
+    def fetch(self):
+        if self.community_input == "":
+            town_data = self._ecoharmonogram_pl.fetch_town(self.town_input)
+        else:
+            town_data = self._ecoharmonogram_pl.fetch_town_with_community(
+                self.community_input
+            )
+
+        matching_towns = list(
+            filter(
+                lambda x: self.town_input.lower() in x.get("name").lower(),
+                town_data.get("towns"),
+            )
+        )
+        matching_towns_district = list(
+            filter(
+                lambda x: self.district_input.lower() in x.get("district").lower(),
+                matching_towns,
+            )
+        )
+
+        if len(matching_towns) == 0:
+            raise SourceArgumentNotFoundWithSuggestions(
+                "town",
+                self.town_input,
+                {x.get("name") for x in town_data.get("towns", [])},
+            )
+        if len(matching_towns_district) == 0:
+            raise SourceArgumentNotFoundWithSuggestions(
+                "district",
+                self.district_input,
+                {x.get("district") for x in matching_towns},
+            )
+
+        town = matching_towns_district[0]
+
+        if len(matching_towns_district) > 1:
+            match = False
+            for town_district in matching_towns_district:
+                if (
+                    self.town_input.lower() == town_district.get("name").lower()
+                    and self.district_input.lower()
+                    == town_district.get("district").lower()
+                ):
+                    match = True
+                    town = town_district
+                    break
+            if not match:
+                matches = [
+                    ("town: " + x.get("name") + ", district:" + x.get("district"))
+                    for x in matching_towns_district
+                ]
+
+                raise Exception(
+                    f"Found multiple matches but no exact match found {matches}"
+                )
+
+        schedule_periods_data = self._ecoharmonogram_pl.fetch_scheduled_periods(town)
+        schedule_periods = schedule_periods_data.get("schedulePeriods")
+
+        entries = []
+        for sp in schedule_periods:
+            entries.extend(self._create_entries(sp, town))
+        return entries
+
+    def _entry_exists(self, dmy, name, entries: list[Collection]):
+        for e in entries:
+            if dmy == e.date and name == e.type:
+                return True
+        return False
+
+    def _get_streets_with_group(self, sp: SchedulePeriod, town: Town) -> StreetResponse:
+        groupId = "1"
+        choosedStreetIds = ""
+        counter = 0
+        streets: StreetResponse = {
+            "streets": [],
+            "groups": {"items": [], "groupId": ""},
+        }
+        while groupId != "":  # Prevent infinite loop (should probably never happen)
+            counter += 1
+            if counter > 6:
+                raise Exception("Infinite loop detected while fetching groups")
+            streets = self._ecoharmonogram_pl.fetch_streets(
+                sp,
+                town,
+                self.street_input,
+                self.house_number_input,
+                groupId,
+                choosedStreetIds,
+            )
+
+            groupId = streets["groups"]["groupId"]
+            if len(streets["groups"]["items"]) != 0 and groupId in self._groups:
+                for g_name, val in self._groups.items():
+                    if groupId != g_name:
+                        continue
+                    if val == "":
+                        raise SourceArgumentRequiredWithSuggestions(
+                            g_name,
+                            val,
+                            {x["name"] for x in streets["groups"]["items"]},
+                        )
+                    group_match = None
+                    for group in streets["groups"]["items"]:
+                        if group["name"].lower().casefold() == val.lower().casefold():
+                            group_match = group
+                            choosedStreetIds = group["choosedStreetIds"]
+                    if group_match is None:
+                        raise SourceArgumentNotFoundWithSuggestions(
+                            g_name,
+                            val,
+                            {x["name"] for x in streets["groups"]["items"]},
+                        )
+
+        if len(streets["streets"]) == 1:
+            return streets
+
+        if len(streets["streets"]) == 0:
+            raise SourceArgumentNotFound(
+                "street",
+                self.street_input,
+            )
+
+        available_regions = {
+            (street.get("region") or "").strip()
+            for street in streets["streets"]
+            if (street.get("region") or "").strip()
+        }
+        _LOGGER.debug("Available regions: %s", available_regions)
+
+        to_return: list[Street] = []
+        for street in streets["streets"]:
+            if not (
+                street["sides"] == ""
+                or (
+                    self.additional_sides_matcher_input != ""
+                    and (
+                        street["sides"].lower().casefold()
+                        == self.additional_sides_matcher_input.lower().casefold()
+                    )
+                )
+            ):
+                continue
+
+            if self.region_input != "":
+                street_region = (street.get("region") or "").strip()
+                if street_region.casefold() == self.region_input.strip().casefold():
+                    to_return.append(street)
+                continue
+
+            to_return.append(street)
+
+        if len(to_return) == 0:
+            if self.region_input != "":
+                raise SourceArgumentNotFoundWithSuggestions(
+                    "region",
+                    self.region_input,
+                    sorted(available_regions),
+                )
+            if self.additional_sides_matcher_input != "":
+                raise SourceArgumentNotFoundWithSuggestions(
+                    "additional_sides_matcher",
+                    self.additional_sides_matcher_input,
+                    {x["sides"] for x in streets["streets"]},
+                )
+            raise SourceArgumentRequiredWithSuggestions(
+                "additional_sides_matcher",
+                self.additional_sides_matcher_input,
+                {x["sides"] for x in streets["streets"]},
+            )
+
+        # Only ask for a region when the streets that are still candidates
+        # after house-number narrowing sit in more than one *named* region
+        # (e.g. "Nowy Ramiszów" vs "Stary Ramiszów"). Streets without a
+        # region, or a house-number match that already picks one region
+        # (e.g. Rzeszów, Krakowska 317E), must keep working without it.
+        if len(to_return) > 1 and self.region_input == "":
+            candidate_regions = {
+                (s.get("region") or "").strip()
+                for s in self._filter_streets_by_house_number(to_return)
+            } - {""}
+            if len(candidate_regions) > 1:
+                raise SourceArgumentRequiredWithSuggestions(
+                    "region",
+                    self.region_input,
+                    sorted(candidate_regions),
+                )
+
+        return {**streets, "streets": to_return}
+
+    @staticmethod
+    def _extract_number(value: str) -> int | None:
+        """Return the leading integer from a house-number string, e.g. '317E' → 317."""
+        m = re.match(r"(\d+)", value.strip())
+        return int(m.group(1)) if m else None
+
+    def _filter_streets_by_house_number(self, streets: list[Street]) -> list[Street]:
+        """Narrow down streets to those matching the configured house number.
+
+        The API returns all streets in a group regardless of the searched house
+        number.  When multiple streets in the same group carry different
+        schedules (e.g. Rzeszów – Krakowska has per-house-number routes), we
+        need to pick only the street(s) that best match the user's house number.
+
+        Matching priority:
+        1. Exact match on ``numbers`` field (e.g. "7/B" == "7/B").
+        2. Exact match on ``numberFrom`` field.
+        3. Range match: ``numberFrom`` ≤ house_number ≤ ``numberTo``
+           (open upper bound when ``numberTo`` is empty).
+        Falls back to the full list when nothing matches.
+        """
+        if len(streets) <= 1 or not self.house_number_input:
+            return streets
+
+        hn = self.house_number_input.strip()
+        hn_int = self._extract_number(hn)
+
+        # 1. exact match on numbers
+        exact = [s for s in streets if s.get("numbers", "").strip() == hn]
+        if exact:
+            return exact
+
+        # 2. exact match on numberFrom
+        exact_from = [s for s in streets if s.get("numberFrom", "").strip() == hn]
+        if exact_from:
+            return exact_from
+
+        # 3. range match (needs a numeric house number)
+        if hn_int is not None:
+            range_match = []
+            for s in streets:
+                from_val = self._extract_number(s.get("numberFrom", ""))
+                to_val = self._extract_number(s.get("numberTo", ""))
+                if from_val is None:
+                    continue
+                if from_val <= hn_int:
+                    if to_val is None or hn_int <= to_val:
+                        range_match.append(s)
+            if range_match:
+                return range_match
+
+        return streets
+
+    # Some towns (e.g. Zabrze) encode single-family ("jednorodzinna") vs
+    # multi-family ("wielorodzinna") housing as two different schedule ids
+    # for what looks like a single street. The `sides` field returned for
+    # those ids is identical (it just holds the district name), so it can't
+    # be used to tell them apart. The only reliable signal we've found is
+    # the housing-type letter encoded in the response's top-level `name`
+    # field, e.g. "Hjb_15;Hjmb_17;..." (single-family) vs "Hwb_9;Hwmb_15;..."
+    # (multi-family).
+    _HOUSING_TYPE_LABELS: ClassVar[dict[str, str]] = {
+        "j": "Zabudowa jednorodzinna",
+        "w": "Zabudowa wielorodzinna",
+    }
+
+    @classmethod
+    def _derive_housing_type_label(cls, schedules_response: ScheduleResponse) -> str:
+        """Best-effort housing-type label derived from the schedule-name prefix.
+
+        Returns "" when the response doesn't match the known "Hj"/"Hw"
+        prefix pattern, i.e. when it can't be used to disambiguate.
+        """
+        name = schedules_response.get("name") or ""
+        first_token = name.split(";", 1)[0]
+        match = re.match(r"^H([jw])", first_token)
+        if not match:
+            return ""
+        return cls._HOUSING_TYPE_LABELS[match.group(1)]
+
+    def _append_schedule_entries(
+        self, schedules_response: ScheduleResponse, entries: list[Collection]
+    ) -> None:
+        schedules_raw = schedules_response["schedules"]
+        schedules_descriptions_dict = dict[str, ScheduleDescription]()
+        schedules_descriptions_raw = schedules_response["scheduleDescription"]
+
+        for sd in schedules_descriptions_raw:
+            schedules_descriptions_dict[sd["id"]] = sd
+
+        schedules: list[ScheduleWithName] = []
+        for sr in schedules_raw:
+            z: ScheduleWithName = cast(ScheduleWithName, sr.copy())
+            z["name"] = schedules_descriptions_dict[sr["scheduleDescriptionId"]]["name"]
+            schedules.append(z)
+
+        for sch in schedules:
+            days = sch["days"].split(";")
+            month = sch["month"]
+            year = sch["year"]
+            for d in days:
+                d = d.strip()
+                if not d:
+                    continue
+                try:
+                    dmy = datetime.date(int(year), int(month), int(d))
+                except ValueError:
+                    _LOGGER.warning(
+                        "ecoharmonogram_pl: skipping invalid date %s-%s-%s for %s",
+                        year,
+                        month,
+                        d,
+                        sch["name"],
+                    )
+                    continue
+                name = sch["name"]
+                if not self._entry_exists(dmy, name, entries):
+                    entries.append(Collection(dmy, name))
+
+    def _create_entries(self, sp: SchedulePeriod, town: Town) -> list[Collection]:
+        streets = self._get_streets_with_group(sp, town)
+        streets_list = self._filter_streets_by_house_number(streets["streets"])
+
+        entries: list[Collection] = []
+        for street in streets_list:
+            street_ids = street["id"].split(",")
+
+            if len(street_ids) == 1:
+                # Fast path: unchanged legacy behaviour for the common case.
+                schedules_response = self._ecoharmonogram_pl.fetch_schedules(
+                    sp, street_ids[0]
+                )
+                if (
+                    self.additional_sides_matcher_input.lower()
+                    in schedules_response["street"]["sides"].lower()
+                ):
+                    self._append_schedule_entries(schedules_response, entries)
+                if self.additional_sides_matcher_input == "":
+                    return entries
+                continue
+
+            # A single street entry bundles multiple ids (e.g. Zabrze splits
+            # single-family and multi-family housing into two ids for the
+            # same street name). Fetch all of them up front so we can decide
+            # whether `sides` already disambiguates them.
+            fetched: list[tuple[str, ScheduleResponse]] = [
+                (streetId, self._ecoharmonogram_pl.fetch_schedules(sp, streetId))
+                for streetId in street_ids
+            ]
+            sides_by_id = [resp["street"]["sides"] for _, resp in fetched]
+
+            if len({s.lower() for s in sides_by_id}) > 1:
+                # `sides` differs between ids - keep existing behaviour and
+                # let additional_sides_matcher filter on it as before.
+                for _streetId, schedules_response in fetched:
+                    if (
+                        self.additional_sides_matcher_input.lower()
+                        not in schedules_response["street"]["sides"].lower()
+                    ):
+                        continue
+                    self._append_schedule_entries(schedules_response, entries)
+                if self.additional_sides_matcher_input == "":
+                    return entries
+                continue
+
+            # `sides` is identical (or empty) for every id, so it can't
+            # disambiguate them. Fall back to the housing-type label derived
+            # from the schedule name.
+            derived_labels = [
+                self._derive_housing_type_label(resp) for _, resp in fetched
+            ]
+            distinct_derived = {d for d in derived_labels if d}
+
+            if len(distinct_derived) <= 1:
+                # No known housing-type split detected - preserve legacy
+                # behaviour and merge everything (e.g. Nadolice Wielkie,
+                # where multiple ids for the same house are genuinely meant
+                # to be combined into a single calendar).
+                for _streetId, schedules_response in fetched:
+                    self._append_schedule_entries(schedules_response, entries)
+                if self.additional_sides_matcher_input == "":
+                    return entries
+                continue
+
+            # Multiple genuinely different housing types were found for this
+            # street - require the user to pick one via
+            # additional_sides_matcher instead of silently merging them.
+            if self.additional_sides_matcher_input == "":
+                raise SourceArgumentRequiredWithSuggestions(
+                    "additional_sides_matcher",
+                    "this street has separate schedules for single-family and "
+                    "multi-family housing, please select one",
+                    distinct_derived,
+                )
+
+            matched_any = False
+            for (_streetId, schedules_response), label in zip(
+                fetched, derived_labels, strict=True
+            ):
+                if self.additional_sides_matcher_input.lower() != label.lower():
+                    continue
+                matched_any = True
+                self._append_schedule_entries(schedules_response, entries)
+
+            if not matched_any:
+                raise SourceArgumentNotFoundWithSuggestions(
+                    "additional_sides_matcher",
+                    self.additional_sides_matcher_input,
+                    distinct_derived,
+                )
+        return entries