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

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

@@ -0,0 +1,210 @@
+import re
+from datetime import datetime, timedelta
+
+import requests
+from dateutil import rrule
+from waste_collection_schedule import Collection, Icons
+from waste_collection_schedule.exceptions import (
+    SourceArgAmbiguousWithSuggestions,
+    SourceArgumentNotFoundWithSuggestions,
+)
+
+TITLE = "Sunshine Coast Queensland (QLD)"
+DESCRIPTION = "Source script for Sunshine Coast Queensland (QLD)."
+COUNTRY = "au"
+URL = "https://www.sunshinecoast.qld.gov.au/living-and-community/waste-and-recycling/bin-collection-days"
+TEST_CASES = {
+    "Hospital Rd": {"street_name": "hospital rd"},
+    "Great Keppel Way": {"street_name": "great keppel way"},
+    "House number and suburb": {"street_name": "12 Hospital Rd, Nambour"},
+    "Street type spelled out": {"street_name": "hospital road"},
+    "Street in several suburbs": {"street_name": "Main St", "locality": "Eumundi"},
+}
+
+API_URL = "https://www.sunshinecoast.qld.gov.au/__server__/api/v1"
+ICON_MAP = {
+    "Garbage": Icons.GENERAL_WASTE,
+    "Recycle": Icons.RECYCLING,
+    "Organic": Icons.ORGANIC,
+}
+
+HOW_TO_GET_ARGUMENTS_DESCRIPTION = {
+    "en": (
+        "Use the street name as the council's bin collection page spells it, e.g. "
+        "'Hospital Rd'. A house number and suburb are ignored if you include them. "
+        "Set `locality` to the suburb when the same street name occurs in more than "
+        "one suburb; the error message lists the suburbs to choose from."
+    )
+}
+
+PARAM_DESCRIPTIONS = {
+    "en": {
+        "street_name": "Street name, e.g. Hospital Rd.",
+        "locality": "Suburb, needed only when the street name is not unique.",
+    }
+}
+
+PARAM_TRANSLATIONS = {
+    "en": {
+        "street_name": "Street Name",
+        "locality": "Suburb",
+    }
+}
+
+"""
+    WEEK TYPES
+        sunshine coast uses a week setting
+        week 1 and week 2 starting from a set date
+
+
+    RETURNED VALUES FROM API Query
+        JSON DATA:
+            [{"id":"<id>","street":"<Street Name>","locality":"<Town>","day":"Wednesday","week":"1","instructions":""}]
+"""
+
+BASE_DATE = datetime(2021, 12, 11)
+
+# The API matches a substring of its own street names, which are abbreviated
+# ("Hospital Rd", "Pacific Bvd"), so a spelled-out type finds nothing.
+STREET_TYPE_ABBREVIATIONS = {
+    "avenue": "ave",
+    "boulevard": "bvd",
+    "circuit": "cct",
+    "close": "cl",
+    "court": "ct",
+    "crescent": "cres",
+    "drive": "dr",
+    "esplanade": "esp",
+    "highway": "hwy",
+    "parade": "pde",
+    "place": "pl",
+    "road": "rd",
+    "street": "st",
+    "terrace": "tce",
+}
+
+_HOUSE_NUMBER = re.compile(r"^\d+[a-z]?(?:\s*[-/]\s*\d+[a-z]?)?\s+", re.IGNORECASE)
+
+
+def split_locality(street_name: str) -> tuple[str, str | None]:
+    """Split a "<street>, <suburb>" string into its two parts."""
+    street, _, locality = street_name.partition(",")
+    return street.strip(), locality.strip() or None
+
+
+def query_candidates(street_name: str) -> list[str]:
+    """Return the API queries to try for a user-supplied street name.
+
+    Users copy the address from the council's page, so the street name can carry
+    a house number, a suburb, or a spelled-out street type. None of those match
+    the API, which searches its abbreviated street names for a substring.
+    """
+    street = _HOUSE_NUMBER.sub("", split_locality(street_name)[0], count=1).strip()
+    street = " ".join(street.split())
+
+    candidates = [street]
+    words = street.split()
+    if words:
+        last = words[-1].lower()
+        abbreviated = STREET_TYPE_ABBREVIATIONS.get(last)
+        if abbreviated:
+            candidates.append(" ".join([*words[:-1], abbreviated]))
+        # drop the street type entirely as a last resort
+        if len(words) > 1 and (
+            abbreviated or last in STREET_TYPE_ABBREVIATIONS.values()
+        ):
+            candidates.append(" ".join(words[:-1]))
+
+    ordered: list[str] = []
+    for candidate in candidates:
+        if candidate and candidate.casefold() not in {o.casefold() for o in ordered}:
+            ordered.append(candidate)
+    return ordered
+
+
+def start_date(day_name: str, week: str) -> datetime:
+    """First collection day of a street's week 1 / week 2 cycle."""
+    day = BASE_DATE
+    for _ in range(7):
+        if day.strftime("%A") == day_name:
+            break
+        day += timedelta(days=1)
+    return day + timedelta(weeks=int(week) - 1)
+
+
+class Source:
+    def __init__(self, street_name, locality=None):
+        self.street_name = str(street_name).strip()
+        self._locality = str(locality).strip() if locality else None
+        if self._locality is None:
+            self._locality = split_locality(self.street_name)[1]
+
+    def _query(self, street: str) -> list[dict]:
+        r = requests.get(f"{API_URL}/streets/{street}", timeout=30)
+        r.raise_for_status()
+        results = r.json()
+        return results if isinstance(results, list) else []
+
+    def _street(self) -> dict:
+        """Find the one street record matching the configured arguments."""
+        results: list[dict] = []
+        for candidate in query_candidates(self.street_name):
+            results = self._query(candidate)
+            if results:
+                break
+
+        if not results:
+            raise SourceArgumentNotFoundWithSuggestions(
+                "street_name", self.street_name, []
+            )
+
+        matches = results
+        if self._locality:
+            wanted = self._locality.casefold()
+            matches = [r for r in results if r.get("locality", "").casefold() == wanted]
+            if not matches:
+                raise SourceArgumentNotFoundWithSuggestions(
+                    "locality",
+                    self._locality,
+                    sorted({r["locality"] for r in results}),
+                )
+
+        if len(matches) > 1:
+            raise SourceArgAmbiguousWithSuggestions(
+                "street_name",
+                self.street_name,
+                sorted(f"{r['street']}, {r['locality']}" for r in matches),
+            )
+
+        return matches[0]
+
+    def fetch(self):
+        data = self._street()
+
+        day = start_date(data["day"], data["week"])
+        today = datetime.today()
+
+        general_dates = rrule.rrule(rrule.WEEKLY, dtstart=day).xafter(today, 10, True)
+        recycling_dates = rrule.rrule(rrule.WEEKLY, interval=2, dtstart=day).xafter(
+            today, 10, True
+        )
+        garden_dates = rrule.rrule(
+            rrule.WEEKLY, interval=2, dtstart=day + timedelta(weeks=1)
+        ).xafter(today, 10, True)
+
+        entries = []
+        for text, dates in [
+            ("Garbage", general_dates),
+            ("Recycle", recycling_dates),
+            ("Organic", garden_dates),
+        ]:
+            for date in dates:
+                entries.append(
+                    Collection(
+                        date=date.date(),
+                        t=text,
+                        icon=ICON_MAP[text],
+                    )
+                )
+
+        return entries

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

@@ -0,0 +1,198 @@
+import logging
+
+import requests
+from waste_collection_schedule import Collection, Icons
+from waste_collection_schedule.exceptions import SourceArgumentNotFound
+
+from ..service.WhatBinDay import WhatBinDayService
+
+_LOGGER = logging.getLogger(__name__)
+
+TITLE = "Surf Coast Shire"
+DESCRIPTION = "Source for Surf Coast Shire (VIC) waste collection."
+URL = "https://www.surfcoast.vic.gov.au"
+COUNTRY = "au"
+
+NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
+
+HOW_TO_GET_ARGUMENTS_DESCRIPTION = {
+    "en": (
+        "Visit the Surf Coast Shire 'Bin collection calendars' page "
+        "(https://www.surfcoast.vic.gov.au/Property/Waste-and-recycling/Kerbside-bins/Bin-collection-calendars), "
+        "search for your address, and enter the street number, street name, "
+        "suburb and postcode exactly as they appear (suburb must be in "
+        "Title Case, e.g. 'Torquay', not 'TORQUAY')."
+    )
+}
+
+PARAM_DESCRIPTIONS = {
+    "en": {
+        "street_number": "Street number (e.g. '20')",
+        "street_name": "Street name (e.g. 'Bell Street')",
+        "suburb": "Suburb, in Title Case (e.g. 'Torquay')",
+        "post_code": "Postcode (e.g. '3228')",
+    }
+}
+
+PARAM_TRANSLATIONS = {
+    "en": {
+        "street_number": "Street number",
+        "street_name": "Street name",
+        "suburb": "Suburb",
+        "post_code": "Post code",
+    }
+}
+
+TEST_CASES = {
+    "Bell Street Torquay": {
+        "street_number": "20",
+        "street_name": "Bell Street",
+        "suburb": "Torquay",
+        "post_code": "3228",
+    },
+    "Mountjoy Parade Lorne": {
+        "street_number": "1",
+        "street_name": "Mountjoy Parade",
+        "suburb": "Lorne",
+        "post_code": "3232",
+    },
+    "Noble Street Anglesea": {
+        "street_number": "1",
+        "street_name": "Noble Street",
+        "suburb": "Anglesea",
+        "post_code": "3230",
+    },
+}
+
+
+ICON_MAP = {
+    "WasteBin": Icons.GENERAL_WASTE,
+    "RecycleBin": Icons.RECYCLING,
+    "GreenBin": Icons.ORGANIC,
+    "GlassBin": Icons.GLASS,
+}
+
+BIN_NAMES = {
+    "WasteBin": "General waste (landfill)",
+    "RecycleBin": "Recycling",
+    "GreenBin": "Food and garden waste",
+    "GlassBin": "Glass",
+}
+
+
+class Source:
+    def __init__(
+        self, street_number: str, street_name: str, suburb: str, post_code: str
+    ):
+        self.street_number = str(street_number)
+        self.street_name = str(street_name)
+        # Surf Coast Shire's WhatBinDay backend matches the suburb name
+        # case-sensitively against its own dataset (e.g. "Torquay", not
+        # "TORQUAY"), so normalise user input to Title Case.
+        self.suburb = str(suburb).strip().title()
+        self.post_code = str(post_code)
+
+        self._service = WhatBinDayService(
+            location_key=(
+                f"{self.street_number}_{self.street_name}_"
+                f"{self.suburb}_{self.post_code}"
+            ),
+            icon_map=ICON_MAP,
+            bin_names=BIN_NAMES,
+            app_package="com.socketsoftware.whatbinday.surfcoast",
+        )
+
+    def _geocode(self) -> dict:
+        """Resolve the address to coordinates via Nominatim.
+
+        Surf Coast Shire's roster lookup requires coordinates close to the
+        actual property (unlike some other WhatBinDay-backed councils, a
+        generic/default coordinate does not resolve to any bin service),
+        so we geocode the full address first.
+        """
+        query = (
+            f"{self.street_number} {self.street_name}, "
+            f"{self.suburb} VIC {self.post_code}, Australia"
+        )
+        response = requests.get(
+            NOMINATIM_URL,
+            params={
+                "q": query,
+                "format": "json",
+                "limit": "1",
+                "countrycodes": "au",
+            },
+            headers={"User-Agent": "hacs_waste_collection_schedule"},
+            timeout=30,
+        )
+        response.raise_for_status()
+        results = response.json()
+        if not results:
+            raise SourceArgumentNotFound("street_name", self.street_name)
+
+        return {
+            "lat": float(results[0]["lat"]),
+            "lng": float(results[0]["lon"]),
+        }
+
+    def _build_location_data(self, coordinates: dict) -> dict:
+        """Build the WhatBinDay address payload.
+
+        The shared WhatBinDayService.build_address_data() helper uses the
+        same string for both the state's long_name and short_name. Surf
+        Coast Shire's backend requires the full state name ("Victoria") as
+        the long_name, so the payload is built manually here instead of
+        via that helper.
+        """
+        formatted_address = (
+            f"{self.street_number} {self.street_name}, "
+            f"{self.suburb} VIC {self.post_code}, Australia"
+        )
+        return {
+            "address_components": [
+                {
+                    "long_name": self.street_number,
+                    "short_name": self.street_number,
+                    "types": ["street_number"],
+                },
+                {
+                    "long_name": self.street_name,
+                    "short_name": self.street_name,
+                    "types": ["route"],
+                },
+                {
+                    "long_name": self.suburb,
+                    "short_name": self.suburb,
+                    "types": ["locality", "political"],
+                },
+                {
+                    "long_name": self.post_code,
+                    "short_name": self.post_code,
+                    "types": ["postal_code"],
+                },
+                {
+                    "long_name": "Victoria",
+                    "short_name": "VIC",
+                    "types": ["administrative_area_level_1", "political"],
+                },
+                {
+                    "long_name": "Australia",
+                    "short_name": "AU",
+                    "types": ["country", "political"],
+                },
+            ],
+            "formatted_address": formatted_address,
+            "geometry": {
+                "location": coordinates,
+                "location_type": "APPROXIMATE",
+            },
+        }
+
+    def fetch(self) -> list[Collection]:
+        coordinates = self._geocode()
+        location_data = self._build_location_data(coordinates)
+
+        entries = self._service.get_collection_schedule(location_data)
+        if not entries:
+            raise SourceArgumentNotFound("street_name", self.street_name)
+        return entries

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

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+from datetime import date, timedelta
+
+import requests
+from waste_collection_schedule import Collection, Icons  # type: ignore[attr-defined]
+from waste_collection_schedule.exceptions import (
+    SourceArgumentNotFound,
+    SourceArgumentNotFoundWithSuggestions,
+)
+
+TITLE = "Sutherland Shire Council"
+DESCRIPTION = "Source for Sutherland Shire Council, NSW, Australia."
+URL = "https://www.sutherlandshire.nsw.gov.au"
+COUNTRY = "au"
+TEST_CASES = {
+    "5 Cleveland Place, BONNET BAY": {
+        "suburb": "BONNET BAY",
+        "street": "Cleveland Place",
+        "house_number": "5",
+    },
+    "20 Waratah Street, CRONULLA": {
+        "suburb": "CRONULLA",
+        "street": "Waratah Street",
+        "house_number": "20",
+    },
+    # The council's own administration building, and the only Zone 1 case
+    # here: both of the above are Zone 2, so nothing exercised the other
+    # fortnight.
+    "4-20 Eton Street, SUTHERLAND": {
+        "suburb": "SUTHERLAND",
+        "street": "Eton Street",
+        "house_number": "4-20",
+    },
+}
+
+ICON_MAP = {
+    "Garbage": Icons.GENERAL_WASTE,
+    "Recycling": Icons.RECYCLING,
+    "Garden Waste": Icons.GARDEN,
+}
+
+PARAM_TRANSLATIONS = {
+    "en": {
+        "suburb": "Suburb",
+        "street": "Street Name",
+        "house_number": "House Number",
+    },
+}
+
+PARAM_DESCRIPTIONS = {
+    "en": {
+        "suburb": "Suburb, e.g. BONNET BAY.",
+        "street": "Street name spelled out in full, e.g. Cleveland Place.",
+        "house_number": "House number, e.g. 5.",
+    },
+}
+
+HOW_TO_GET_ARGUMENTS_DESCRIPTION = {
+    "en": (
+        "Use the address exactly as it appears on council correspondence — "
+        "street type spelled out in full (Street, Place, Avenue). You can "
+        "check your address on the map at "
+        "https://www.sutherlandshire.nsw.gov.au/living-here/waste-and-recycling/bin-collection"
+    ),
+}
+
+# The council's "When is my bin collected?" page is backed by this public
+# ArcGIS layer (one feature per property, carrying the collection weekday,
+# zone and recycling frequency). The previous ASP.NET dropdown form the old
+# scraper drove was removed from the website in 2026, and the site now also
+# TLS-fingerprints plain library HTTP clients; the GIS endpoint has neither
+# problem.
+_ARCGIS_QUERY_URL = (
+    "https://geoserver.ssc.nsw.gov.au/arcgis/rest/services/WebOnline/MapServer/4/query"
+)
+
+_WEEKDAY_MAP = {
+    "monday": 0,
+    "tuesday": 1,
+    "wednesday": 2,
+    "thursday": 3,
+    "friday": 4,
+    "saturday": 5,
+    "sunday": 6,
+}
+
+# The GIS layer gives a property's zone but nothing about which fortnight is
+# which, so the alternation needs an anchor. This is the Monday of a week the
+# council's own Zone 1 calendar highlights yellow (yellow-lid recycling; green
+# highlight is the green-lid garden week):
+# https://www.sutherlandshire.nsw.gov.au/__data/assets/pdf_file/0020/121934/SSC-Waste-Calendar-2026-27-Zone1-Print.pdf
+_ZONE1_RECYCLING_WEEK = date(2026, 8, 31)
+
+# Whole weeks added before taking the parity. Zone 2's recycling week is Zone
+# 1's garden week; the two published calendars are opposite on every one of the
+# 260 collection days they cover.
+_ZONE_WEEK_OFFSETS: dict[str, int] = {
+    "1": 0,
+    "2": 1,
+}
+
+_SCHEDULE_WEEKS = 52
+
+
+def _next_weekday(from_date: date, weekday: int) -> date:
+    """Return the next occurrence of weekday on or after from_date."""
+    days_ahead = weekday - from_date.weekday()
+    if days_ahead < 0:
+        days_ahead += 7
+    return from_date + timedelta(days=days_ahead)
+
+
+def _generate_collections(
+    weekday: int, zone: str, start: date, end: date, weekly_recycling: bool
+) -> list[Collection]:
+    """Generate all collection dates between start and end.
+
+    Garbage is weekly. Recycling and garden waste alternate fortnights by
+    zone; properties flagged for weekly recycling (some unit blocks) get
+    recycling every week on top of the fortnightly garden collection.
+    """
+    week_offset = _ZONE_WEEK_OFFSETS.get(zone, 0)
+    cur = _next_weekday(start, weekday)
+    entries: list[Collection] = []
+
+    while cur <= end:
+        entries.append(Collection(date=cur, t="Garbage", icon=ICON_MAP["Garbage"]))
+
+        # The anchor is a Monday, so flooring the day difference by 7 buckets
+        # each collection into its own Monday-to-Sunday week.
+        week = (cur - _ZONE1_RECYCLING_WEEK).days // 7
+        if (week + week_offset) % 2 == 0:
+            waste_type = "Recycling"
+        else:
+            waste_type = "Garden Waste"
+            if weekly_recycling:
+                entries.append(
+                    Collection(date=cur, t="Recycling", icon=ICON_MAP["Recycling"])
+                )
+        entries.append(Collection(date=cur, t=waste_type, icon=ICON_MAP[waste_type]))
+
+        cur += timedelta(weeks=1)
+
+    return entries
+
+
+def _sql_quote(value: str) -> str:
+    return value.replace("'", "''")
+
+
+class Source:
+    def __init__(self, suburb: str, street: str, house_number: str):
+        self._suburb = suburb.upper().strip()
+        self._street = street.strip()
+        self._house_number = str(house_number).strip()
+
+    def _query(self, where: str, record_count: int = 50) -> list[dict]:
+        r = requests.get(
+            _ARCGIS_QUERY_URL,
+            params={
+                "where": where,
+                "outFields": "situ1,situ2,DAY_OF_WEEK,ZONE_NO,RECYCLE_PICKUP",
+                "returnGeometry": "false",
+                "resultRecordCount": str(record_count),
+                "f": "json",
+            },
+            timeout=30,
+        )
+        r.raise_for_status()
+        data = r.json()
+        if "error" in data:
+            raise ValueError(
+                f"Sutherland Shire GIS query failed: {data['error'].get('message')}"
+            )
+        return [f["attributes"] for f in data.get("features", [])]
+
+    def fetch(self) -> list[Collection]:
+        address = _sql_quote(f"{self._house_number} {self._street}".upper())
+        suburb = _sql_quote(self._suburb)
+
+        features = self._query(
+            f"UPPER(situ1) = '{address}' AND UPPER(situ2) LIKE '{suburb}%'"
+        )
+        if not features:
+            # Unit prefixes ("5/20 Waratah Street") and minor spacing quirks.
+            features = self._query(
+                f"UPPER(situ1) LIKE '{address}%' AND UPPER(situ2) LIKE '{suburb}%'"
+            )
+        if not features:
+            # Nothing for that house number — suggest addresses on the street.
+            street_matches = self._query(
+                f"UPPER(situ1) LIKE '%{_sql_quote(self._street.upper())}%'"
+                f" AND UPPER(situ2) LIKE '{suburb}%'"
+            )
+            if street_matches:
+                raise SourceArgumentNotFoundWithSuggestions(
+                    "house_number",
+                    self._house_number,
+                    sorted({f["situ1"] for f in street_matches}),
+                )
+            raise SourceArgumentNotFound("street", f"{self._street}, {self._suburb}")
+
+        attrs = features[0]
+        day_name = str(attrs.get("DAY_OF_WEEK", "")).strip().lower()
+        weekday = _WEEKDAY_MAP.get(day_name)
+        if weekday is None:
+            raise ValueError(
+                f"Unknown collection day {attrs.get('DAY_OF_WEEK')!r} for "
+                f"{attrs.get('situ1')}, {attrs.get('situ2')}"
+            )
+        zone = str(attrs.get("ZONE_NO", "1"))
+        weekly_recycling = (
+            str(attrs.get("RECYCLE_PICKUP", "")).strip().lower() == "weekly"
+        )
+
+        today = date.today()
+        end_date = today + timedelta(weeks=_SCHEDULE_WEEKS)
+        return _generate_collections(weekday, zone, today, end_date, weekly_recycling)

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

@@ -0,0 +1,52 @@
+from time import sleep
+
+from curl_cffi import requests
+from waste_collection_schedule import Collection, Icons  # type: ignore[attr-defined]
+from waste_collection_schedule.service.ICS import ICS
+
+TITLE = "Sutton Council, London"
+DESCRIPTION = "Source for Sutton Council, London."
+URL = "https://sutton.gov.uk"
+TEST_CASES = {"4721996": {"id": 4721996}, "4499298": {"id": "4499298"}}
+
+
+ICON_MAP = {
+    "non-recyclable": Icons.GENERAL_WASTE,
+    "paper": Icons.PAPER,
+    "mixed": Icons.RECYCLING,
+    "food": Icons.BIO_KITCHEN,
+}
+
+
+API_URL = "https://waste-services.sutton.gov.uk/waste/{id}"
+ICAL_URL = API_URL + "/calendar.ics"
+
+
+class Source:
+    def __init__(self, id: str | int):
+        self._id: str | int = id
+        self._ics = ICS()
+
+    def fetch(self):
+        s = requests.Session(impersonate="chrome")
+
+        api_url = API_URL.format(id=self._id)
+        ical_url = ICAL_URL.format(id=self._id)
+
+        r = s.get(api_url)
+        while f'hx-get="/waste/{self._id}"' in r.text:
+            sleep(2)
+            r = s.get(api_url)
+        r.raise_for_status()
+
+        r = s.get(ical_url)
+        r.raise_for_status()
+
+        dates = self._ics.convert(r.text)
+        entries = []
+        for d in dates:
+            entries.append(
+                Collection(d[0], d[1], ICON_MAP.get(d[1].split(" ")[0].lower()))
+            )
+
+        return entries