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

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

@@ -0,0 +1,108 @@
+import datetime
+
+import requests
+from waste_collection_schedule import Collection  # type: ignore[attr-defined]
+from waste_collection_schedule.exceptions import SourceArgumentNotFoundWithSuggestions
+
+TITLE = "Armadale (Western Australia)"
+DESCRIPTION = "Source for Armadale (Western Australia)."
+URL = "https://my.armadale.wa.gov.au"
+TEST_CASES = {
+    "23 Sexty St, ARMADALE": {"address": "23 Sexty St, ARMADALE"},
+    "270 Skeet Rd, HARRISDALE": {"address": "270 Skeet Rd, HARRISDALE"},
+}
+
+WEEKDAYS = {
+    "Monday": 0,
+    "Tuesday": 1,
+    "Wednesday": 2,
+    "Thursday": 3,
+    "Friday": 4,
+    "Saturday": 5,
+    "Sunday": 6,
+}
+
+API_URL = "https://api.my.armadale.wa.gov.au/bins"
+
+
+def easter(year):
+    # taken from dateutil easter https://dateutil.readthedocs.io/en/stable/_modules/dateutil/easter.html to prevent dependency
+
+    y = year
+    g = y % 19
+    e = 0
+
+    # New method
+    c = y // 100
+    h = (c - c // 4 - (8 * c + 13) // 25 + 19 * g + 15) % 30
+    i = h - (h // 28) * (1 - (h // 28) * (29 // (h + 1)) * ((21 - g) // 11))
+    j = (y + y // 4 + i + 2 - c + c // 4) % 7
+
+    # p can be from -6 to 56 corresponding to dates 22 March to 23 May
+    # (later dates apply to method 2, although 23 May never actually occurs)
+    p = i - j + e
+    d = 1 + (p + 27 + (p + 6) // 40) % 31
+    m = 3 + (p + 26) // 30
+    return datetime.date(int(y), int(m), int(d))
+
+
+class Source:
+    def __init__(self, address: str):
+        self._address: str = address
+
+    def fetch(self):
+        r = requests.get(API_URL, params={"address": self._address})
+        r.raise_for_status()
+
+        data = r.json()
+        if not data:
+            raise SourceArgumentNotFoundWithSuggestions("address", self._address, [])
+
+        result = data[0]
+        bin_day = result["bin_day"]
+        if bin_day not in WEEKDAYS:
+            raise Exception(f"Unknown bin day: {bin_day}")
+        bin_day = WEEKDAYS[bin_day]
+
+        recycling: bool = result["recycle_area"].lower().startswith("this week")
+
+        current_day = datetime.datetime.now().date()
+
+        diff_to_next = (bin_day - current_day.weekday()) % 7
+
+        # next is next week
+        if current_day.weekday() + diff_to_next >= 7:
+            recycling = not recycling
+
+        current_day = current_day + datetime.timedelta(days=diff_to_next)
+
+        entries = []
+        for _i in range(52):
+            date = current_day
+            start_of_week = date - datetime.timedelta(days=date.weekday())
+
+            christmas = datetime.date(current_day.year, 12, 25)
+            new_years_day = datetime.date(
+                current_day.year + (1 if current_day.month == 12 else 0), 1, 1
+            )
+            good_friday = easter(current_day.year) - datetime.timedelta(days=2)
+
+            if (
+                start_of_week <= christmas <= date
+                or start_of_week <= new_years_day <= date
+            ):
+                # if christmas or new years day is in the current week
+                if 0 <= christmas.weekday() < 5:  # if christmas is on a weekday
+                    date += datetime.timedelta(days=1)
+
+            if date == good_friday:
+                date += datetime.timedelta(days=1)
+
+            entries.append(Collection(date=date, t="rubbish", icon="mdi:trash-can"))
+            if recycling:
+                entries.append(Collection(date=date, t="recycling", icon="mdi:recycle"))
+
+            current_day += datetime.timedelta(days=7)
+            recycling = not recycling
+
+        return entries

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

@@ -0,0 +1,104 @@
+import re
+from datetime import datetime
+
+import requests
+from bs4 import BeautifulSoup
+from waste_collection_schedule import Collection, Icons
+
+TITLE = "Armagh City Banbridge & Craigavon"
+DESCRIPTION = "Source for Armagh City Banbridge & Craigavon."
+URL = "https://www.armaghbanbridgecraigavon.gov.uk"
+TEST_CASES = {
+    "BT667ES": {"address_id": 185622007},
+    "BT63 5GY": {"address_id": "187318004"},
+}
+ICON_MAP = {
+    "Domestic": Icons.GENERAL_WASTE,
+    "Recycling": Icons.RECYCLING,
+    "Garden & Food": Icons.BIO_KITCHEN,
+}
+API_URL = "https://www.armaghbanbridgecraigavon.gov.uk/resident/binday-result/"
+HOW_TO_GET_ARGUMENTS_DESCRIPTION = {
+    "en": "Find the parameter of your address using https://www.armaghbanbridgecraigavon.gov.uk/resident/when-is-my-bin-day/, after selecting your address. The address ID is the number at the end of the URL after `address=`.",
+}
+
+
+class Source:
+    def __init__(self, address_id: int):
+        self._address_id: int = address_id
+
+    def fetch(self) -> list[Collection]:
+        args = {"address": self._address_id}
+
+        # Add headers to avoid being blocked as a bot
+        headers = {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
+        }
+
+        r = requests.get(API_URL, params=args, headers=headers)
+        r.raise_for_status()
+
+        soup = BeautifulSoup(r.text, "html.parser")
+
+        # The new structure uses h2 tags with icons for collection types
+        headings = soup.find_all("h2")
+
+        if not headings:
+            raise Exception("No headings found while parsing the response HTML.")
+
+        entries = []
+
+        for heading in headings:
+            # Get the bin type text from the h2
+            heading_text = heading.get_text(strip=True)
+
+            # Skip if not a collection type heading
+            if "Collections" not in heading_text:
+                continue
+
+            # Clean up the bin type name
+            bin_type = heading_text.replace("Collections", "").strip()
+
+            # Skip empty or invalid types
+            if not bin_type:
+                continue
+
+            icon = ICON_MAP.get(bin_type)
+
+            # Find the parent div with class containing 'col-sm-12'
+            parent_div = heading.find_parent(
+                "div", class_=lambda x: x and "col-sm-12" in x
+            )
+
+            if not parent_div:
+                continue
+
+            # Find the next sibling div that contains the dates
+            dates_div = parent_div.find_next_sibling(
+                "div", class_=lambda x: x and "col-sm-12" in x and "col-md-9" in x
+            )
+
+            if not dates_div:
+                continue
+
+            # Find all h4 tags containing the dates
+            date_elements = dates_div.find_all("h4")
+
+            for date_elem in date_elements:
+                date_text = date_elem.get_text(strip=True)
+
+                # The date text includes an icon, so we need to extract just the date
+                # Format is typically: "11/11/2025"
+                # We need to find the date pattern
+                date_match = re.search(r"\d{2}/\d{2}/\d{4}", date_text)
+
+                if date_match:
+                    date_str = date_match.group()
+                    try:
+                        date = datetime.strptime(date_str, "%d/%m/%Y").date()
+                        entries.append(Collection(date=date, t=bin_type, icon=icon))
+                    except ValueError:
+                        # Skip invalid dates
+                        continue
+
+        return entries

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

@@ -0,0 +1,90 @@
+import logging
+from urllib.parse import quote
+
+import requests
+from waste_collection_schedule import Collection, Icons  # type: ignore[attr-defined]
+from waste_collection_schedule.service.ICS import ICS
+
+TITLE = "ART Trier (Depreciated)"
+DESCRIPTION = "Source for waste collection of ART Trier."
+URL = "https://www.art-trier.de"
+TEST_CASES = {
+    "Trier": {
+        "zip_code": "54296",
+        "district": "Stadt Trier, Universitätsring",
+    },  # # https://www.art-trier.de/ics-feed/54296_trier_universitaetsring_1-1800.ics
+    "Schweich": {
+        "zip_code": "54338",
+        "district": "Schweich (inkl. Issel)",
+    },  # https://www.art-trier.de/ics-feed/54338_schweich_inkl_issel_1-1800.ics
+    "Dreis": {
+        "zip_code": "54518",
+        "district": "Dreis",
+    },  # https://www.art-trier.de/ics-feed/54518_dreis_1-1800.ics
+    "Wittlich Marktplatz": {
+        "zip_code": "54516",
+        "district": "Wittlich, Marktplatz",
+    },  # https://www.art-trier.de/ics-feed/54516_wittlich_marktplatz_1-1800.ics
+    "Wittlich Wengerohr": {
+        "zip_code": "54516",
+        "district": "Wittlich-Wengerohr",
+    },  # https://www.art-trier.de/ics-feed/54516_wittlich%2Dwengerohr_1-1800.ics
+}
+
+API_URL = "https://www.art-trier.de/ics-feed"
+REMINDER_DAY = (
+    "0"  # The calendar event should be on the same day as the waste collection
+)
+REMINDER_TIME = "0600"  # The calendar event should start on any hour of the correct day, so this does not matter much
+ICON_MAP = {
+    "Altpapier": Icons.PAPER,
+    "Restmüll": Icons.GENERAL_WASTE,
+    "Gelber Sack": Icons.PLASTIC_PACKAGING,
+}
+SPECIAL_CHARS = str.maketrans(
+    {
+        " ": "_",
+        "ä": "ae",
+        "ü": "ue",
+        "ö": "oe",
+        "ß": "ss",
+        "(": None,
+        ")": None,
+        ",": None,
+        ".": None,
+    }
+)
+LOGGER = logging.getLogger(__name__)
+
+PARAM_TRANSLATIONS = {
+    "de": {
+        "zip_code": "PLZ",
+        "district": "Ort",
+    }
+}
+
+
+class Source:
+    def __init__(self, district: str, zip_code: str):
+        self._district = quote(
+            district.lower().removeprefix("stadt ").translate(SPECIAL_CHARS).strip()
+        )
+        self._zip_code = zip_code
+        self._ics = ICS(regex=r"^A.R.T. Abfuhrtermin: (.*)", split_at=r" & ")
+
+    def fetch(self):
+        LOGGER.warning(
+            "The ART Trier source is deprecated and might not work with all addresses anymore."
+            " Please use the ICS instead: https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/doc/ics/art_trier_de.md"
+        )
+        url = f"{API_URL}/{self._zip_code}:{self._district}::@{REMINDER_DAY}-{REMINDER_TIME}.ics"
+
+        res = requests.get(url)
+        res.raise_for_status()
+
+        schedule = self._ics.convert(res.text)
+
+        return [
+            Collection(date=entry[0], t=entry[1], icon=ICON_MAP.get(entry[1]))
+            for entry in schedule
+        ]

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

@@ -0,0 +1,66 @@
+from waste_collection_schedule import Collection, Icons  # type: ignore[attr-defined]
+from waste_collection_schedule.exceptions import SourceArgumentRequired
+from waste_collection_schedule.service.uk_cloud9_apps import Cloud9Client
+
+TITLE = "Arun District Council"
+DESCRIPTION = "Source for arun.gov.uk services for Arun District, UK."
+URL = "https://www.arun.gov.uk"
+TEST_CASES = {
+    "Test_001": {"postcode": "BN17 5JA", "address": "21A Beach Road, Littlehampton"},
+    "Test_002": {"postcode": "BN16 1AA", "address": "2 Downs Way, East Preston"},
+    "Test_003": {"uprn": 100062180214},
+    "Test_004": {"uprn": "0100062180214"},
+}
+HOW_TO_GET_ARGUMENTS_DESCRIPTION = {
+    "en": "You can find your UPRN by visiting [Find My Address](https://www.findmyaddress.co.uk) and entering your address details."
+}
+PARAM_TRANSLATIONS = {
+    "en": {
+        "uprn": "Unique Property Reference Number (UPRN)",
+        "postcode": "Postcode (legacy, use UPRN instead)",
+        "address": "Address (legacy, use UPRN instead)",
+    }
+}
+PARAM_DESCRIPTIONS = {
+    "en": {
+        "uprn": "Unique Property Reference Number (UPRN)",
+        "postcode": "Postcode (legacy, use UPRN instead)",
+        "address": "Address (legacy, use UPRN instead)",
+    }
+}
+ICON_MAP = {
+    "garden": Icons.GARDEN,
+    "food": Icons.BIO_KITCHEN,
+    "recycl": Icons.RECYCLING,
+    "waste": Icons.GENERAL_WASTE,
+    "rubbish": Icons.GENERAL_WASTE,
+    "refuse": Icons.GENERAL_WASTE,
+}
+
+
+class Source:
+    def __init__(
+        self,
+        uprn: str | int | None = None,
+        postcode: str | None = None,
+        address: str | None = None,
+    ):
+        self._client = Cloud9Client("arun", icon_keywords=ICON_MAP)
+        self._uprn = str(uprn) if uprn else None
+        self._postcode = postcode
+        self._address = address
+
+    def fetch(self) -> list[Collection]:
+        if self._uprn:
+            return self._client.fetch_by_uprn(self._uprn)
+        if not self._postcode:
+            raise SourceArgumentRequired("uprn", "Provide a UPRN or postcode + address")
+        return self._client.fetch_by_address(
+            postcode=self._postcode,
+            address_string=self._address or "",
+            # The client's suggestions are whole address strings and it reports
+            # the address it was given as the offending value, so they belong to
+            # the address argument: picking one has to refine `address`, not
+            # overwrite the postcode with a full address.
+            argument_name="address",
+        )

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

@@ -0,0 +1,126 @@
+import datetime
+
+import requests
+from waste_collection_schedule import Collection, Icons
+from waste_collection_schedule.exceptions import (
+    SourceArgumentNotFound,
+    SourceArgumentNotFoundWithSuggestions,
+)
+
+TITLE = "Ashfield District Council"
+DESCRIPTION = "Source for ashfield.gov.uk, Ashfield District Council, UK"
+URL = "https://www.ashfield.gov.uk"
+TEST_CASES = {
+    "11 Maun View Gardens, Sutton-in-Ashfield": {"uprn": 10001336299},
+    "101 Main Street, Huthwaite": {"post_code": "NG17 2LQ", "uprn": "100031253415"},
+    "1 Acacia Avenue, Kirkby-in-Ashfield": {"post_code": "NG17 9BH", "number": "1"},
+    "Council Offices, Kirkby-in-Ashfield": {
+        "post_code": "NG178ZA",
+        "name": "COUNCIL OFFICES",
+    },
+}
+
+API_URLS = {
+    "address_search": "https://www.ashfield.gov.uk/api/address/search/{postcode}",
+    "collection": "https://www.ashfield.gov.uk/api/address/collections/{uprn}",
+}
+
+ICON_MAP = {
+    "Residual Waste Collection Service": Icons.GENERAL_WASTE,
+    "Domestic Recycling Collection Service": Icons.GENERAL_WASTE,
+    "Domestic Glass Collection Service": Icons.GLASS,
+    "Garden Waste Collection Service": Icons.GARDEN,
+}
+
+NAMES = {
+    "Residual Waste Collection Service": "Red (rubbish)",
+    "Domestic Recycling Collection Service": "Green (recycling)",
+    "Domestic Glass Collection Service": "Blue (glass)",
+    "Garden Waste Collection Service": "Brown (garden)",
+}
+
+
+class Source:
+    def __init__(self, post_code=None, number=None, name=None, uprn=None):
+        self._post_code = post_code
+        self._number = number
+        self._name = name
+        self._uprn = uprn
+
+    def fetch(self):
+        if not self._uprn:
+            if not self._post_code:
+                raise ValueError("post_code is required when uprn is not provided")
+            if not (self._name or self._number):
+                raise ValueError(
+                    "Either name or number must be provided when uprn is not provided"
+                )
+            # look up the UPRN for the address
+            q = str(API_URLS["address_search"]).format(postcode=self._post_code)
+            r = requests.get(q, timeout=30)
+            r.raise_for_status()
+            addresses = r.json()["results"]
+
+            if not addresses:
+                raise SourceArgumentNotFound("post_code", self._post_code)
+
+            matching = []
+            if self._name:
+                name_cf = self._name.casefold()
+                for x in addresses:
+                    dpa = x.get("DPA") or {}
+                    building_name = dpa.get("BUILDING_NAME")
+                    if building_name and building_name.casefold() == name_cf:
+                        matching.append(x)
+            elif self._number:
+                for x in addresses:
+                    dpa = x.get("DPA") or {}
+                    if dpa.get("BUILDING_NUMBER") == self._number:
+                        matching.append(x)
+
+            if matching:
+                first_dpa = matching[0].get("DPA") or {}
+                uprn_value = first_dpa.get("UPRN")
+                if uprn_value:
+                    self._uprn = int(uprn_value)
+
+            if not self._uprn:
+                raise SourceArgumentNotFoundWithSuggestions(
+                    argument=(
+                        "name"
+                        if self._name
+                        else "number"
+                        if self._number
+                        else "post_code"
+                    ),
+                    value=self._name or self._number or self._post_code,
+                    suggestions=[
+                        f"{(x.get('DPA') or {}).get('BUILDING_NUMBER', '')} {(x.get('DPA') or {}).get('BUILDING_NAME', '')}".strip()
+                        for x in addresses
+                    ],
+                )
+        else:
+            # Ensure UPRN is an integer
+            self._uprn = int(self._uprn)
+
+        q = str(API_URLS["collection"]).format(uprn=self._uprn)
+
+        r = requests.get(q, timeout=30)
+        r.raise_for_status()
+
+        collections = r.json()["collections"]
+        entries = []
+
+        if collections:
+            for collection in collections:
+                entries.append(
+                    Collection(
+                        date=datetime.datetime.strptime(
+                            collection["date"], "%d/%m/%Y %H:%M:%S"
+                        ).date(),
+                        t=NAMES.get(collection["service"], collection["service"]),
+                        icon=ICON_MAP.get(collection["service"]),
+                    )
+                )
+
+        return entries

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

@@ -0,0 +1,150 @@
+import logging
+import re
+import ssl
+from datetime import datetime
+
+import requests
+from bs4 import BeautifulSoup
+from requests.adapters import HTTPAdapter
+from waste_collection_schedule import Collection, Icons  # type: ignore[attr-defined]
+
+_LOGGER = logging.getLogger(__name__)
+
+TITLE = "Ashford Borough Council"
+DESCRIPTION = "Source for Ashford Borough Council."
+URL = "https://ashford.gov.uk"
+TEST_CASES = {
+    "100060796052": {"uprn": 100060796052, "postcode": "TN23 3DY"},
+    "100060780440": {"uprn": "100060780440", "postcode": "TN24 9JD"},
+    "100062558476": {"uprn": "100062558476", "postcode": "TN233LX"},
+}
+ICON_MAP = {
+    "household refuse": Icons.GENERAL_WASTE,
+    "food waste": Icons.BIO_KITCHEN,
+    "garden waste": Icons.GARDEN,
+    "recycling": Icons.RECYCLING,
+}
+API_URL = "https://secure.ashford.gov.uk/waste/collectiondaylookup/"
+
+
+class LegacyTLSAdapter(HTTPAdapter):
+    # Modern python libraries reject Ashford's server settings and return SSL errors,
+    # Try and force requests to use downgraded settings
+    def init_poolmanager(self, *args, **kwargs):
+        ctx = ssl.create_default_context()
+        ctx.set_ciphers("AES256-SHA256")  # Explicitly use this cipher
+        ctx.minimum_version = ssl.TLSVersion.TLSv1_2  # Explicitly use this TLS version
+        ctx.maximum_version = ssl.TLSVersion.TLSv1_2  # Explicitly use this TLS version
+        kwargs["ssl_context"] = ctx
+        return super().init_poolmanager(*args, **kwargs)
+
+
+class Source:
+    def __init__(self, postcode: str, uprn: str | int):
+        self._uprn = str(uprn).strip()
+        self._postcode = str(postcode).strip()
+
+    def fetch(self):
+
+        _LOGGER.warning(
+            "Forcing requests to use legacy TLSv1.2 & AES256-SHA256 to match ashford.gov.uk website"
+        )
+
+        # Use customised TLS/cipher settings
+        s = requests.Session()
+        s.mount("https://", LegacyTLSAdapter())
+
+        headers = {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
+            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+            "Application": "application/x-www-form-urlencoded",
+        }
+        s.headers.update(headers)
+        r = s.get(API_URL)
+        r.raise_for_status()
+        soup: BeautifulSoup = BeautifulSoup(r.text, "html.parser")
+
+        args = {}
+        for input_tag in soup.find_all("input"):
+            if not input_tag.get("name"):
+                continue
+            args[input_tag["name"]] = input_tag.get("value")
+        args["ctl00$ContentPlaceHolder1$CollectionDayLookup2$HiddenField_UPRN"] = ""
+        args["ctl00$ContentPlaceHolder1$CollectionDayLookup2$TextBox_PostCode"] = (
+            self._postcode
+        )
+        args["ctl00$ContentPlaceHolder1$CollectionDayLookup2$Button_PostCodeSearch"] = (
+            "Continue+>"
+        )
+        args["__EVENTTARGET"] = ""
+        args["__EVENTARGUMENT"] = ""
+
+        r = s.post(API_URL, data=args)
+        r.raise_for_status()
+
+        soup: BeautifulSoup = BeautifulSoup(r.text, "html.parser")
+        args = {}
+        for input_tag in soup.find_all("input"):
+            if not input_tag.get("name"):
+                continue
+            args[input_tag["name"]] = input_tag.get("value")
+        args[
+            "ctl00$ContentPlaceHolder1$CollectionDayLookup2$DropDownList_Addresses"
+        ] = self._uprn
+
+        args["ctl00$ContentPlaceHolder1$CollectionDayLookup2$Button_PostCodeSearch"] = (
+            "Continue+>"
+        )
+        del args["ctl00$ContentPlaceHolder1$CollectionDayLookup2$Button_SelectAddress"]
+        del args["ctl00$ContentPlaceHolder1$CollectionDayLookup2$Button_PostCodeSearch"]
+        args["ctl00$ContentPlaceHolder1$CollectionDayLookup2$Button_SelectAddress"] = (
+            "Continue+>"
+        )
+
+        r = s.post(API_URL, data=args)
+        if r.status_code != 200:
+            raise Exception(
+                f"could not get correct data for your postcode ({self._postcode}). check {API_URL} to validate your arguments."
+            )
+
+        soup: BeautifulSoup = BeautifulSoup(r.text, "html.parser")
+        bin_tables = soup.find_all("table")
+        if bin_tables == []:
+            raise Exception(
+                f"could not get valid data from ashford.gov.uk. is your UPRN ({self._uprn}) correct for postcode ({self._postcode})? check https://uprn.uk/{self._uprn} and {API_URL}"
+            )
+
+        entries = []
+        for bin_table in bin_tables:
+            bin_text = bin_table.find("td", id=re.compile("CollectionDayLookup2_td_"))
+            if not bin_text:
+                continue
+
+            bin_type_soup = bin_text.find("b")
+
+            if not bin_type_soup:
+                continue
+            bin_type: str = bin_type_soup.text.strip()
+
+            date_soup = bin_text.find(
+                "span", id=re.compile(r"CollectionDayLookup2_Label_\w*_Date")
+            )
+            if not date_soup or (
+                " " not in date_soup.text.strip()
+                and date_soup.text.strip().lower() != "today"
+            ):
+                continue
+            date_str: str = date_soup.text.strip()
+            try:
+                if date_soup.text.strip().lower() == "today":
+                    date = datetime.now().date()
+                else:
+                    date = datetime.strptime(date_str.split(" ")[1], "%d/%m/%Y").date()
+
+            except ValueError:
+                continue
+
+            icon = ICON_MAP.get(bin_type.split("(")[0].strip().lower())
+            entries.append(Collection(date=date, t=bin_type, icon=icon))
+
+        return entries