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

package/python/vendor/waste_collection_schedule/__init__.py

@@ -0,0 +1,4 @@
+from .collection import Collection, CollectionBase, CollectionGroup  # type: ignore # isort:skip # noqa: F401
+from .collection_aggregator import CollectionAggregator  # noqa: F401
+from .icons import Icons  # noqa: F401
+from .source_shell import Customize, SourceShell  # noqa: F401

package/python/vendor/waste_collection_schedule/collection.py

@@ -0,0 +1,162 @@
+import datetime
+
+
+class CollectionBase(dict):  # inherit from dict to enable JSON serialization
+    def __init__(
+        self,
+        date: datetime.date,
+        icon: str | None = None,
+        picture: str | None = None,
+        location: str | None = None,
+        description: str | None = None,
+    ):
+        dict.__init__(self, date=date.isoformat(), icon=icon, picture=picture)
+        self._date = date  # store date also as python date object
+
+        loc = _clean_optional_str(location)
+        if loc is not None:
+            self["location"] = loc
+        desc = _clean_optional_str(description)
+        if desc is not None:
+            self["description"] = desc
+
+    @property
+    def date(self):
+        return self._date
+
+    @property
+    def daysTo(self):
+        return (self._date - datetime.datetime.now().date()).days
+
+    @property
+    def icon(self):
+        return self["icon"]
+
+    def set_icon(self, icon: str):
+        self["icon"] = icon
+
+    @property
+    def picture(self):
+        return self["picture"]
+
+    def set_picture(self, picture: str):
+        self["picture"] = picture
+
+    @property
+    def location(self):
+        return self.get("location")
+
+    @property
+    def description(self):
+        return self.get("description")
+
+    def set_location(self, location: str | None):
+        loc = _clean_optional_str(location)
+        if loc is None:
+            self.pop("location", None)
+        else:
+            self["location"] = loc
+
+    def set_description(self, description: str | None):
+        desc = _clean_optional_str(description)
+        if desc is None:
+            self.pop("description", None)
+        else:
+            self["description"] = desc
+
+    def set_date(self, date: datetime.date):
+        self._date = date
+        self["date"] = date.isoformat()
+
+
+def _clean_optional_str(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        value = str(value)
+    stripped = value.strip()
+    return stripped or None
+
+
+class Collection(CollectionBase):
+    def __init__(
+        self,
+        date: datetime.date,
+        t: str,
+        icon: str | None = None,
+        picture: str | None = None,
+        location: str | None = None,
+        description: str | None = None,
+    ):
+        CollectionBase.__init__(
+            self,
+            date=date,
+            icon=icon,
+            picture=picture,
+            location=location,
+            description=description,
+        )
+        self["type"] = t
+
+    @property
+    def type(self) -> str:
+        return self["type"]
+
+    def set_type(self, t: str):
+        self["type"] = t
+
+    def __repr__(self):
+        return f"Collection{{date={self.date}, type={self.type}}}"
+
+
+class CollectionGroup(CollectionBase):
+    def __init__(self, date: datetime.date):
+        CollectionBase.__init__(self, date=date)
+
+    @staticmethod
+    def create(group: list[Collection]):
+        """Create from list of Collection's."""
+        x = CollectionGroup(group[0].date)
+        if len(group) == 1:
+            x.set_icon(group[0].icon)
+            x.set_picture(group[0].picture)
+        else:
+            x.set_icon(f"mdi:numeric-{len(group)}-box-multiple")
+        x["types"] = [it.type for it in group]
+
+        ordered_locs: list[str] = []
+        for it in group:
+            loc = it.get("location")
+            if isinstance(loc, str) and loc.strip():
+                ordered_locs.append(loc.strip())
+        unique_locs = list(dict.fromkeys(ordered_locs))
+        if unique_locs:
+            x["locations"] = unique_locs
+            x["location"] = ", ".join(unique_locs)
+
+        ordered_descs: list[str] = []
+        for it in group:
+            desc = it.get("description")
+            if isinstance(desc, str) and desc.strip():
+                ordered_descs.append(desc.strip())
+        unique_descs = list(dict.fromkeys(ordered_descs))
+        if unique_descs:
+            x["descriptions"] = unique_descs
+            x["description"] = ", ".join(unique_descs)
+
+        return x
+
+    @property
+    def types(self) -> list[str]:
+        return self["types"]
+
+    @property
+    def locations(self):
+        return self.get("locations")
+
+    @property
+    def descriptions(self):
+        return self.get("descriptions")
+
+    def __repr__(self):
+        return f"CollectionGroup{{date={self.date}, types={self.types}}}"

package/python/vendor/waste_collection_schedule/collection_aggregator.py

@@ -0,0 +1,128 @@
+import itertools
+import logging
+from collections.abc import Iterable, Sequence
+from datetime import datetime, timedelta
+
+from . import CollectionGroup
+from .collection import Collection
+from .source_shell import SourceShell
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CollectionAggregator:
+    def __init__(self, shells: Sequence[SourceShell]):
+        self._shells = shells
+
+    @property
+    def _entries(self) -> list[Collection]:
+        """Merge all entries from all connected sources."""
+        return [e for s in self._shells for e in s._entries]
+
+    @property
+    def refreshtime(self):
+        """Simply return the timestamp of the first source."""
+        return self._shells[0].refreshtime
+
+    @property
+    def types(self):
+        """Return set() of all collection types."""
+        return {e.type for e in self._entries}
+
+    def get_upcoming(
+        self,
+        count: int | None = None,
+        leadtime: int | None = None,
+        include_types: Iterable[str] | None = None,
+        exclude_types: Iterable[str] | None = None,
+        include_today: bool = False,
+        start_index: int | None = None,
+    ) -> list[Collection]:
+        """Return list of all entries, limited by count and/or leadtime.
+
+        Keyword arguments:
+        count -- limits the number of returned entries (default=10)
+        leadtime -- limits the timespan in days of returned entries (default=7, 0 = today)
+        """
+        return self._filter(
+            self._entries,
+            count=count,
+            leadtime=leadtime,
+            include_types=include_types,
+            exclude_types=exclude_types,
+            include_today=include_today,
+            start_index=start_index,
+        )
+
+    def get_upcoming_group_by_day(
+        self,
+        count: int | None = None,
+        leadtime: int | None = None,
+        include_types: Iterable[str] | None = None,
+        exclude_types: Iterable[str] | None = None,
+        include_today: bool = False,
+        start_index: int | None = None,
+    ) -> list[CollectionGroup]:
+        """Return list of all entries, grouped by day, limited by count and/or leadtime."""
+        entries = []
+
+        iterator = itertools.groupby(
+            self._filter(
+                self._entries,
+                leadtime=leadtime,
+                include_types=include_types,
+                exclude_types=exclude_types,
+                include_today=include_today,
+            ),
+            lambda e: e.date,
+        )
+
+        for _key, group in iterator:
+            entries.append(CollectionGroup.create(list(group)))
+        if start_index is not None:
+            entries = entries[start_index:]
+        if count is not None:
+            entries = entries[:count]
+
+        return entries
+
+    def _filter(
+        self,
+        entries,
+        count: int | None = None,
+        leadtime: int | None = None,
+        include_types: Iterable[str] | None = None,
+        exclude_types: Iterable[str] | None = None,
+        include_today: bool = False,
+        start_index: int | None = None,
+    ) -> list[Collection]:
+        # remove unwanted waste types from include list
+        if include_types is not None:
+            entries = list(filter(lambda e: e.type in set(include_types), entries))
+
+        # remove unwanted waste types from exclude list
+        if exclude_types is not None:
+            entries = list(filter(lambda e: e.type not in set(exclude_types), entries))
+
+        # remove expired entries
+        now = datetime.now().date()
+        if include_today:
+            entries = list(filter(lambda e: e.date >= now, entries))
+        else:
+            entries = list(filter(lambda e: e.date > now, entries))
+
+        # remove entries which are too far in the future (0 = today)
+        if leadtime is not None:
+            x = now + timedelta(days=leadtime)
+            entries = list(filter(lambda e: e.date <= x, entries))
+
+        # ensure that entries are sorted by date
+        entries.sort(key=lambda e: e.date)
+
+        # remove surplus entries
+        if start_index is not None:
+            entries = entries[start_index:]
+        if count is not None:
+            entries = entries[:count]
+
+        return entries

package/python/vendor/waste_collection_schedule/exceptions.py

@@ -0,0 +1,208 @@
+from collections.abc import Iterable
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class SourceArgumentExceptionMultiple(Exception):
+    """Error base class for errors associated with multiple arguments."""
+
+    def __init__(self, arguments: Iterable[str], message: str) -> None:
+        """Initialize the SourceArgumentExceptionMultiple.
+
+        Args:
+            arguments (Iterable[str]): an iterable of arguments the source arguments (written exactly like in the source __init__).
+            message (str): Message to be displayed for all provided arguments.
+        """
+        self._arguments = arguments
+        self.message = message
+        super().__init__(self.message)
+
+    @property
+    def arguments(self) -> Iterable[str]:
+        return self._arguments
+
+
+class SourceArgumentException(Exception):
+    def __init__(self, argument: str, message: str) -> None:
+        """Initialize the SourceArgumentException.
+
+        Args:
+            argument (str): The source argument that caused the exception (written exactly like in the source __init__).
+            message (str): Message to be displayed for the provided argument.
+        """
+        self._argument = argument
+        self.message = message
+        super().__init__(self.message)
+
+    @property
+    def argument(self) -> str:
+        return self._argument
+
+
+class SourceArgumentSuggestionsExceptionBase(SourceArgumentException, Generic[T]):
+    """Base class for exceptions that provide suggestions for a source argument."""
+
+    def __init__(
+        self,
+        argument: str,
+        message: str,
+        suggestions: Iterable[T],
+        message_addition: str = "",
+    ):
+        """Initialize the SourceArgumentSuggestionsExceptionBase.
+
+        Args:
+            argument (str): The source argument that caused the exception (written exactly like in the source __init__).
+            message (str): Message to be displayed for the provided argument.
+            suggestions (Iterable[T]): An iterable of suggestions for the provided argument.
+            message_addition (str, optional): Additional message appended after the main message adding additional information. Defaults to "".
+        """
+        self._simple_message = message
+        message += f", {message_addition}" if message_addition else ""
+        super().__init__(argument=argument, message=message)
+        self._suggestions = suggestions
+        self._suggestion_type: type[T] | None = (
+            type(next(iter(suggestions))) if suggestions else None
+        )
+
+    @property
+    def suggestions(self) -> Iterable[T]:
+        return self._suggestions
+
+    @property
+    def suggestion_type(self) -> type[T] | None:
+        return self._suggestion_type
+
+    @property
+    def simple_message(self) -> str:
+        return self._simple_message
+
+
+class SourceArgumentNotFound(SourceArgumentException):
+    """Invalid source arguments provided."""
+
+    def __init__(
+        self,
+        argument: str,
+        value: Any,
+        message_addition="please check the spelling and try again.",
+    ) -> None:
+        """Initialize the SourceArgumentNotFound.
+
+        Args:
+            argument (str): The source argument that caused the exception (written exactly like in the source __init__).
+            value (Any): The value of that source argument.
+            message_addition (str, optional): Additional message information. Defaults to "please check the spelling and try again.".
+        """
+        self._simple_message = f"We could not find values for the argument '{argument}' with the value '{value}'"
+        self.message = self._simple_message
+        if message_addition:
+            self.message += f", {message_addition}"
+        super().__init__(argument, self.message)
+
+    @property
+    def simple_message(self) -> str:
+        return self._simple_message
+
+
+class SourceArgumentNotFoundWithSuggestions(SourceArgumentSuggestionsExceptionBase):
+    """Invalid source arguments provided but suggestions provided.
+
+    This should be raised if a source argument is not valid but you want to provide suggestions to the user what they could use instead.
+    """
+
+    def __init__(self, argument: str, value: Any, suggestions: Iterable[T]) -> None:
+        """Initialize the SourceArgumentNotFoundWithSuggestions.
+
+        Args:
+            argument (str): The source argument that caused the exception (written exactly like in the source __init__).
+            value (Any): The value of that source argument.
+            suggestions (Iterable[T]): An iterable of suggestions for the provided argument.
+        """
+        message = f"We could not find values for the argument '{argument}' with the value '{value}'"
+        suggestions = list(suggestions)
+        if len(suggestions) == 0:
+            message += ", We could not find any suggestions. Please also check other arguments."
+            message_addition = ""
+        else:
+            message_addition = (
+                f"you may want to use one of the following: {suggestions}"
+            )
+        super().__init__(
+            argument=argument,
+            message=message,
+            message_addition=message_addition,
+            suggestions=suggestions,
+        )
+
+
+class SourceArgAmbiguousWithSuggestions(SourceArgumentSuggestionsExceptionBase):
+    """Multiple values found for the argument with suggestions provided.
+
+    This should be raised if a there are multiple different results matching the source argument and you want to provide suggestions to the user what they could use instead.
+    """
+
+    def __init__(self, argument: str, value: Any, suggestions: Iterable[T]) -> None:
+        """Initialize the SourceArgAmbiguousWithSuggestions.
+
+        Args:
+            argument (str): The source argument that caused the exception (written exactly like in the source __init__).
+            value (Any): The value of that source argument.
+            suggestions (Iterable[T]): An iterable of suggestions for the provided argument.
+        """
+        message = f"Multiple values found for the argument '{argument}' with the value '{value}'"
+        message_addition = f"please specify one of: {suggestions}"
+        super().__init__(
+            argument=argument,
+            message=message,
+            suggestions=suggestions,
+            message_addition=message_addition,
+        )
+
+
+class SourceArgumentRequired(SourceArgumentException):
+    """Argument must be provided.
+
+    This should be raised if a source argument is required but not provided by the user.
+    """
+
+    def __init__(self, argument: str, reason: str) -> None:
+        """Initialize the SourceArgumentRequired.
+
+        Args:
+            argument (str): The source argument that is required but not provided (written exactly like in the source __init__).
+            reason (str): The reason why the source argument is required.
+        """
+        self.message = f"Argument '{argument}' must be provided"
+        if reason:
+            self.message += f", {reason}"
+        super().__init__(argument, self.message)
+
+
+class SourceArgumentRequiredWithSuggestions(SourceArgumentSuggestionsExceptionBase):
+    """Argument must be provided.
+
+    This should be raised if a source argument is required but not provided by the user and you want to provide suggestions to the user what they could use.
+    """
+
+    def __init__(self, argument: str, reason: str, suggestions: Iterable[T]) -> None:
+        """Initialize the SourceArgumentRequiredWithSuggestions.
+
+        Args:
+            argument (str): The source argument that is required but not provided (written exactly like in the source __init__).
+            reason (str): The reason why the source argument is required.
+            suggestions (Iterable[T]): An iterable of suggestions for the provided argument.
+        """
+        message = f"Argument '{argument}' must be provided"
+        message_addition = (
+            f"you may want to use one of the following: {list(suggestions)}"
+        )
+        if reason:
+            message += f", {reason}"
+        super().__init__(
+            argument=argument,
+            message=message,
+            message_addition=message_addition,
+            suggestions=suggestions,
+        )

package/python/vendor/waste_collection_schedule/icons.py

@@ -0,0 +1,107 @@
+"""Canonical Material Design Icon (MDI) catalogue for waste-collection sources.
+
+Source modules should map their waste-type strings (``t``) to members of the
+:class:`Icons` enum rather than raw ``"mdi:..."`` strings. This keeps the icon
+choice consistent across the ~600 source modules in the repository for the
+same logical waste category. See issue #2813 for the motivation.
+
+If your provider has a waste type that doesn't fit any canonical category,
+open an issue before adding a raw ``mdi:*`` string — the catalogue is
+intentionally small.
+
+Because :class:`Icons` is a :class:`~enum.StrEnum`, members are also strings::
+
+    >>> Icons.GENERAL_WASTE == "mdi:trash-can"
+    True
+    >>> str(Icons.GENERAL_WASTE)
+    'mdi:trash-can'
+
+so existing code paths that compare-as-string keep working.
+"""
+
+import sys
+from enum import Enum
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+
+    class StrEnum(str, Enum):  # type: ignore[no-redef]
+        """Python 3.10 backport of :class:`enum.StrEnum` (added in 3.11)."""
+
+        def __str__(self) -> str:
+            return str(self.value)
+
+
+class Icons(StrEnum):
+    """Canonical MDI icons for waste-collection categories."""
+
+    # General mixed/landfill waste
+    GENERAL_WASTE = "mdi:trash-can"
+
+    # Combustible waste for household, for example in Japan
+    COMBUSTIBLE = "mdi:fire"
+
+    # Non-combustible waste for household, for example in Japan
+    NON_COMBUSTIBLE = "mdi:fire-off"
+
+    # Mixed dry recycling
+    RECYCLING = "mdi:recycle"
+
+    # Plastic/light-packaging stream (Gelber Sack, yellow bag, LVP, etc.) —
+    # visually distinct from RECYCLING to convey the separate stream.
+    PLASTIC_PACKAGING = "mdi:recycle-variant"
+
+    # Plastic PET bottles distinct from PLASTIC_PACKAGING and GLASS bottles
+    PLASTIC_PET = "mdi:bottle-soda-outline"
+
+    # Paper/cardboard
+    PAPER = "mdi:package-variant"
+
+    # Newspaper/periodicals (rare; most providers fold into PAPER)
+    NEWSPAPER = "mdi:newspaper"
+
+    # Glass — single canonical icon for general glass
+    GLASS = "mdi:bottle-soda"
+
+    # Optional coloured-glass distinction (handful of German municipalities)
+    GLASS_COLORED = "mdi:bottle-wine"
+
+    # Scrap metal
+    METAL = "mdi:nail"
+
+    # Organic waste — umbrella when source doesn't distinguish kitchen vs garden
+    ORGANIC = "mdi:leaf"
+
+    # Kitchen/food organics
+    BIO_KITCHEN = "mdi:food-apple"
+
+    # Garden/yard waste
+    GARDEN = "mdi:flower"
+
+    # Seasonal Christmas tree collections
+    CHRISTMAS_TREE = "mdi:pine-tree"
+
+    # Bulky/hard-rubbish/oversized items
+    BULKY = "mdi:sofa"
+
+    # Hazardous / problem waste
+    HAZARDOUS = "mdi:biohazard"
+
+    # Electronic waste / WEEE
+    ELECTRONICS = "mdi:desktop-classic"
+
+    # Battery collection
+    BATTERY = "mdi:battery"
+
+    # Textile / clothing collection
+    TEXTILE = "mdi:hanger"
+
+    # Commercial / business / dumpster pickups
+    COMMERCIAL = "mdi:factory"
+
+    # One-off events (community recycling day, drop-off events)
+    EVENT = "mdi:calendar"
+
+    # Explicit "no collection" / suspended-service marker
+    NO_COLLECTION = "mdi:calendar-remove"