pynintendoparental 2.3.2__py3-none-any.whl → 2.3.2.1__py3-none-any.whl

pynintendoparental/device.py

@@ -2,32 +2,51 @@
 """Defines a single Nintendo Switch device."""
 
 import asyncio
-
-from datetime import datetime, timedelta, time
+from datetime import datetime, time, timedelta
 from typing import Callable
 
 from pynintendoauth.exceptions import HttpException
 
 from .api import Api
+from .application import Application
 from .const import _LOGGER, DAYS_OF_WEEK
-from .exceptions import (
-    BedtimeOutOfRangeError,
-    DailyPlaytimeOutOfRangeError,
-    InvalidDeviceStateError,
-)
 from .enum import (
     AlarmSettingState,
     DeviceTimerMode,
     FunctionalRestrictionLevel,
     RestrictionMode,
 )
+from .exceptions import (
+    BedtimeOutOfRangeError,
+    DailyPlaytimeOutOfRangeError,
+    InvalidDeviceStateError,
+)
 from .player import Player
 from .utils import is_awaitable
-from .application import Application
 
 
 class Device:
-    """A device"""
+    """A Nintendo Switch device.
+
+    Represents a single Nintendo Switch console with parental controls enabled.
+    This class provides methods to monitor and control various parental control settings.
+
+    Attributes:
+        device_id: Unique identifier for the device.
+        name: User-friendly name/label for the device.
+        model: Device model (e.g., "Switch", "Switch 2").
+        limit_time: Daily playtime limit in minutes (-1 if no limit).
+        today_playing_time: Total playing time for the current day in minutes.
+        today_time_remaining: Remaining playtime for the current day in minutes.
+        players: Dictionary of Player objects keyed by player ID.
+        applications: Dictionary of Application objects keyed by application ID.
+        timer_mode: Current timer mode (DAILY or EACH_DAY_OF_THE_WEEK).
+        bedtime_alarm: Time when bedtime alarm sounds.
+        bedtime_end: Time when bedtime restrictions end.
+        forced_termination_mode: True if software suspension is enabled at playtime limit.
+        alarms_enabled: True if alarms are enabled.
+        last_sync: Timestamp of the last sync with Nintendo servers.
+    """
 
     def __init__(self, api):
         """INIT"""
@@ -65,26 +84,45 @@ class Device:
 
     @property
     def model(self) -> str:
-        """Return the model."""
+        """Return the device model.
+
+        Returns:
+            Device model name (e.g., "Switch", "Switch 2", or "Unknown").
+        """
         model_map = {"P00": "Switch", "P01": "Switch 2"}
         return model_map.get(self.generation, "Unknown")
 
     @property
     def generation(self) -> str | None:
-        """Return the generation."""
+        """Return the device generation code.
+
+        Returns:
+            Platform generation code (e.g., "P00", "P01") or None if unknown.
+        """
         return self.extra.get("platformGeneration", None)
 
     @property
     def last_sync(self) -> float | None:
-        """Return the last time this device was synced."""
-        return self.extra.get("synchronizedParentalControlSetting", {}).get(
-            "synchronizedAt", None
-        )
+        """Return the last time this device was synced with Nintendo servers.
+
+        Returns:
+            Unix timestamp of the last synchronization, or None if never synced.
+        """
+        return self.extra.get("synchronizedParentalControlSetting", {}).get("synchronizedAt", None)
+
+    async def update(self, now: datetime = None):
+        """Update device data from Nintendo servers.
+
+        Fetches the latest information including daily summaries, parental control
+        settings, monthly summaries, and extra device information. Also updates
+        all associated players and applications.
 
-    async def update(self):
-        """Update data."""
+        Args:
+            now: Optional datetime for the update. Defaults to current time if not provided.
+        """
         _LOGGER.debug(">> Device.update()")
-        now = datetime.now()
+        if now is None:
+            now = datetime.now()
         await asyncio.gather(
             self._get_daily_summaries(now),
             self._get_parental_control_setting(now),
@@ -96,15 +134,40 @@ class Device:
         self._update_applications()
         await self._execute_callbacks()
 
-    def add_device_callback(self, callback):
-        """Add a callback to the device."""
+    def add_device_callback(self, callback: Callable):
+        """Add a callback function to be called when device state changes.
+
+        The callback will be invoked whenever the device data is updated.
+        Callbacks can be either synchronous or asynchronous functions.
+
+        Args:
+            callback: A callable function. Can be sync or async.
+
+        Raises:
+            ValueError: If the provided object is not callable.
+
+        Example:
+            ```python
+            async def on_device_update():
+                print("Device updated!")
+
+            device.add_device_callback(on_device_update)
+            ```
+        """
         if not callable(callback):
             raise ValueError("Object must be callable.")
         if callback not in self._callbacks:
             self._callbacks.append(callback)
 
-    def remove_device_callback(self, callback):
-        """Remove a given device callback."""
+    def remove_device_callback(self, callback: Callable):
+        """Remove a previously registered device callback.
+
+        Args:
+            callback: The callback function to remove.
+
+        Raises:
+            ValueError: If the provided object is not callable or not found.
+        """
         if not callable(callback):
             raise ValueError("Object must be callable.")
         if callback in self._callbacks:
@@ -133,37 +196,83 @@ class Device:
         await self._execute_callbacks()
 
     async def set_new_pin(self, pin: str):
-        """Updates the pin for the device."""
+        """Set a new PIN code for parental controls on this device.
+
+        Args:
+            pin: The new PIN code to set. Must be a valid 4-digit string.
+
+        Example:
+            ```python
+            await device.set_new_pin("1234")
+            ```
+        """
         _LOGGER.debug(">> Device.set_new_pin(pin=REDACTED)")
-        await self._send_api_update(
-            self._api.async_update_unlock_code, new_code=pin, device_id=self.device_id
-        )
+        await self._send_api_update(self._api.async_update_unlock_code, new_code=pin, device_id=self.device_id)
 
     async def add_extra_time(self, minutes: int):
-        """Add extra time to the device."""
+        """Add extra playing time for the current day.
+
+        This grants additional playing time beyond the configured daily limit
+        for the current day only. The extra time does not carry over to other days.
+
+        Args:
+            minutes: Number of additional minutes to add (must be positive).
+
+        Example:
+            ```python
+            await device.add_extra_time(30)  # Add 30 minutes
+            ```
+        """
         _LOGGER.debug(">> Device.add_extra_time(minutes=%s)", minutes)
         # This endpoint does not return parental control settings, so we call it directly.
         await self._api.async_update_extra_playing_time(self.device_id, minutes)
         await self._get_parental_control_setting(datetime.now())
 
     async def set_restriction_mode(self, mode: RestrictionMode):
-        """Updates the restriction mode of the device."""
+        """Set the restriction mode for playtime limits.
+
+        Args:
+            mode: The restriction mode to set. Options are:
+                - RestrictionMode.FORCED_TERMINATION: Software will be suspended when playtime limit is reached.
+                - RestrictionMode.ALARM: An alarm will be shown but software won't be suspended.
+
+        Example:
+            ```python
+            from pynintendoparental.enum import RestrictionMode
+
+            await device.set_restriction_mode(RestrictionMode.FORCED_TERMINATION)
+            ```
+        """
         _LOGGER.debug(">> Device.set_restriction_mode(mode=%s)", mode)
-        self.parental_control_settings["playTimerRegulations"]["restrictionMode"] = str(
-            mode
-        )
+        self.parental_control_settings["playTimerRegulations"]["restrictionMode"] = str(mode)
         response = await self._api.async_update_play_timer(
             self.device_id,
             self.parental_control_settings["playTimerRegulations"],
         )
         now = datetime.now()
-        self._parse_parental_control_setting(
-            response["json"], now
-        )  # Don't need to recalculate times
+        self._parse_parental_control_setting(response["json"], now)  # Don't need to recalculate times
         await self._execute_callbacks()
 
     async def set_bedtime_alarm(self, value: time):
-        """Update the bedtime alarm for the device."""
+        """Set the bedtime alarm time.
+
+        The bedtime alarm will sound at the specified time to notify that bedtime has arrived.
+
+        Args:
+            value: Time when the bedtime alarm should sound. Must be between 16:00 (4 PM) and 23:00 (11 PM),
+                  or time(0, 0) to disable the alarm.
+
+        Raises:
+            BedtimeOutOfRangeError: If the time is outside the valid range.
+
+        Example:
+            ```python
+            from datetime import time
+
+            await device.set_bedtime_alarm(time(21, 0))  # Set alarm to 9:00 PM
+            await device.set_bedtime_alarm(time(0, 0))   # Disable alarm
+            ```
+        """
         _LOGGER.debug(">> Device.set_bedtime_alarm(value=%s)", value)
         if not ((16 <= value.hour <= 23) or (value.hour == 0 and value.minute == 0)):
             raise BedtimeOutOfRangeError(value=value)
@@ -180,19 +289,13 @@ class Device:
         else:
             regulation = {**regulation, "endingTime": None}
         if self.timer_mode == DeviceTimerMode.DAILY:
-            _LOGGER.debug(
-                ">> Device.set_bedtime_alarm(value=%s): Daily timer mode", value
-            )
-            self.parental_control_settings["playTimerRegulations"]["dailyRegulations"][
-                "bedtime"
-            ] = regulation
+            _LOGGER.debug(">> Device.set_bedtime_alarm(value=%s): Daily timer mode", value)
+            self.parental_control_settings["playTimerRegulations"]["dailyRegulations"]["bedtime"] = regulation
         else:
-            _LOGGER.debug(
-                ">> Device.set_bedtime_alarm(value=%s): Each day timer mode", value
-            )
-            self.parental_control_settings["playTimerRegulations"][
-                "eachDayOfTheWeekRegulations"
-            ][DAYS_OF_WEEK[now.weekday()]]["bedtime"] = regulation
+            _LOGGER.debug(">> Device.set_bedtime_alarm(value=%s): Each day timer mode", value)
+            self.parental_control_settings["playTimerRegulations"]["eachDayOfTheWeekRegulations"][
+                DAYS_OF_WEEK[now.weekday()]
+            ]["bedtime"] = regulation
         _LOGGER.debug(
             ">> Device.set_bedtime_alarm(value=%s): Updating bedtime with object %s",
             value,
@@ -206,28 +309,46 @@ class Device:
         )
 
     async def set_bedtime_end_time(self, value: time):
-        """Update the bedtime end time for the device."""
+        """Set the time when bedtime restrictions end.
+
+        This sets when the device can be used again after bedtime restrictions.
+
+        Args:
+            value: Time when bedtime ends. Must be between 05:00 (5 AM) and 09:00 (9 AM),
+                  or time(0, 0) to disable bedtime restrictions.
+
+        Raises:
+            BedtimeOutOfRangeError: If the time is outside the valid range.
+
+        Example:
+            ```python
+            from datetime import time
+
+            await device.set_bedtime_end_time(time(7, 0))   # Bedtime ends at 7:00 AM
+            await device.set_bedtime_end_time(time(0, 0))  # Disable bedtime restrictions
+            ```
+        """
         _LOGGER.debug(">> Device.set_bedtime_end_time(value=%s)", value)
         if not time(5, 0) <= value <= time(9, 0) and value != time(0, 0):
             raise BedtimeOutOfRangeError(value=value)
         now = datetime.now()
         if self.timer_mode == DeviceTimerMode.DAILY:
-            regulation = self.parental_control_settings["playTimerRegulations"][
-                "dailyRegulations"
-            ]
+            regulation = self.parental_control_settings["playTimerRegulations"]["dailyRegulations"]
         else:
-            regulation = self.parental_control_settings["playTimerRegulations"][
-                "eachDayOfTheWeekRegulations"
-            ][DAYS_OF_WEEK[now.weekday()]]
+            regulation = self.parental_control_settings["playTimerRegulations"]["eachDayOfTheWeekRegulations"][
+                DAYS_OF_WEEK[now.weekday()]
+            ]
         new_bedtime_settings = {
             **regulation["bedtime"],
             "enabled": regulation["bedtime"]["endingTime"] or value != time(0, 0),
-            "startingTime": {
-                "hour": value.hour,
-                "minute": value.minute,
-            }
-            if value != time(0, 0)
-            else None,
+            "startingTime": (
+                {
+                    "hour": value.hour,
+                    "minute": value.minute,
+                }
+                if value != time(0, 0)
+                else None
+            ),
         }
         regulation["bedtime"] = new_bedtime_settings
         await self._send_api_update(
@@ -238,7 +359,20 @@ class Device:
         )
 
     async def set_timer_mode(self, mode: DeviceTimerMode):
-        """Updates the timer mode of the device."""
+        """Set the timer mode for playtime limits.
+
+        Args:
+            mode: The timer mode to set. Options are:
+                - DeviceTimerMode.DAILY: Single playtime limit for all days.
+                - DeviceTimerMode.EACH_DAY_OF_THE_WEEK: Different limits for each day of the week.
+
+        Example:
+            ```python
+            from pynintendoparental.enum import DeviceTimerMode
+
+            await device.set_timer_mode(DeviceTimerMode.DAILY)
+            ```
+        """
         _LOGGER.debug(">> Device.set_timer_mode(mode=%s)", mode)
         self.timer_mode = mode
         self.parental_control_settings["playTimerRegulations"]["timerMode"] = str(mode)
@@ -257,9 +391,41 @@ class Device:
         bedtime_end: time | None = None,
         max_daily_playtime: int | float | None = None,
     ):
-        """Updates the daily restrictions of a device."""
+        """Set restrictions for a specific day of the week.
+
+        This method only works when timer_mode is set to EACH_DAY_OF_THE_WEEK.
+
+        Args:
+            enabled: Whether to enable playtime restrictions for this day.
+            bedtime_enabled: Whether to enable bedtime restrictions for this day.
+            day_of_week: Day of the week (e.g., "MONDAY", "TUESDAY", etc.).
+            bedtime_start: Time when bedtime restrictions start (required if bedtime_enabled=True).
+            bedtime_end: Time when bedtime restrictions end (required if bedtime_enabled=True).
+            max_daily_playtime: Maximum playtime in minutes for this day (required if enabled=True).
+
+        Raises:
+            InvalidDeviceStateError: If timer_mode is not EACH_DAY_OF_THE_WEEK.
+            ValueError: If day_of_week is invalid.
+            BedtimeOutOfRangeError: If bedtime values are outside valid ranges.
+
+        Example:
+            ```python
+            from datetime import time
+
+            # Set Monday restrictions
+            await device.set_daily_restrictions(
+                enabled=True,
+                bedtime_enabled=True,
+                day_of_week="MONDAY",
+                bedtime_start=time(21, 0),  # 9 PM
+                bedtime_end=time(7, 0),     # 7 AM
+                max_daily_playtime=120      # 2 hours
+            )
+            ```
+        """
         _LOGGER.debug(
-            ">> Device.set_daily_restrictions(enabled=%s, bedtime_enabled=%s, day_of_week=%s, bedtime_start=%s, bedtime_end=%s, max_daily_playtime=%s)",
+            ">> Device.set_daily_restrictions(enabled=%s, bedtime_enabled=%s, day_of_week=%s, "
+            "bedtime_start=%s, bedtime_end=%s, max_daily_playtime=%s)",
             enabled,
             bedtime_enabled,
             day_of_week,
@@ -268,14 +434,10 @@ class Device:
             max_daily_playtime,
         )
         if self.timer_mode != DeviceTimerMode.EACH_DAY_OF_THE_WEEK:
-            raise InvalidDeviceStateError(
-                "Daily restrictions can only be set when timer_mode is EACH_DAY_OF_THE_WEEK."
-            )
+            raise InvalidDeviceStateError("Daily restrictions can only be set when timer_mode is EACH_DAY_OF_THE_WEEK.")
         if day_of_week not in DAYS_OF_WEEK:
             raise ValueError(f"Invalid day_of_week: {day_of_week}")
-        regulation = self.parental_control_settings["playTimerRegulations"][
-            "eachDayOfTheWeekRegulations"
-        ][day_of_week]
+        regulation = self.parental_control_settings["playTimerRegulations"]["eachDayOfTheWeekRegulations"][day_of_week]
 
         if bedtime_enabled and bedtime_start is not None and bedtime_end is not None:
             if not time(5, 0) <= bedtime_start <= time(9, 0):
@@ -321,7 +483,24 @@ class Device:
         )
 
     async def set_functional_restriction_level(self, level: FunctionalRestrictionLevel):
-        """Updates the functional restriction level of a device."""
+        """Set the content restriction level based on age ratings.
+
+        This controls which games and applications can be launched based on their age rating.
+
+        Args:
+            level: The restriction level to set. Options are:
+                - FunctionalRestrictionLevel.CHILD: Suitable for young children.
+                - FunctionalRestrictionLevel.TEEN: Suitable for teenagers.
+                - FunctionalRestrictionLevel.YOUNG_ADULT: Suitable for young adults.
+                - FunctionalRestrictionLevel.CUSTOM: Custom restrictions.
+
+        Example:
+            ```python
+            from pynintendoparental.enum import FunctionalRestrictionLevel
+
+            await device.set_functional_restriction_level(FunctionalRestrictionLevel.TEEN)
+            ```
+        """
         _LOGGER.debug(">> Device.set_functional_restriction_level(level=%s)", level)
         self.parental_control_settings["functionalRestrictionLevel"] = str(level)
         await self._send_api_update(
@@ -331,7 +510,20 @@ class Device:
         )
 
     async def update_max_daily_playtime(self, minutes: int | float = 0):
-        """Updates the maximum daily playtime of a device."""
+        """Set the maximum daily playtime limit.
+
+        Args:
+            minutes: Maximum playtime in minutes (0-360). Use -1 to remove the limit.
+
+        Raises:
+            DailyPlaytimeOutOfRangeError: If minutes is outside the valid range.
+
+        Example:
+            ```python
+            await device.update_max_daily_playtime(180)  # 3 hours
+            await device.update_max_daily_playtime(-1)   # Remove limit
+            ```
+        """
         _LOGGER.debug(">> Device.update_max_daily_playtime(minutes=%s)", minutes)
         if isinstance(minutes, float):
             minutes = int(minutes)
@@ -348,43 +540,34 @@ class Device:
                 self.device_id,
                 minutes,
             )
-            self.parental_control_settings["playTimerRegulations"]["dailyRegulations"][
-                "timeToPlayInOneDay"
-            ]["enabled"] = ttpiod
+            self.parental_control_settings["playTimerRegulations"]["dailyRegulations"]["timeToPlayInOneDay"][
+                "enabled"
+            ] = ttpiod
             if (
                 "limitTime"
-                in self.parental_control_settings["playTimerRegulations"][
-                    "dailyRegulations"
-                ]["timeToPlayInOneDay"]
+                in self.parental_control_settings["playTimerRegulations"]["dailyRegulations"]["timeToPlayInOneDay"]
                 and minutes is None
             ):
-                self.parental_control_settings["playTimerRegulations"][
-                    "dailyRegulations"
-                ]["timeToPlayInOneDay"].pop("limitTime")
+                self.parental_control_settings["playTimerRegulations"]["dailyRegulations"]["timeToPlayInOneDay"].pop(
+                    "limitTime"
+                )
             else:
-                self.parental_control_settings["playTimerRegulations"][
-                    "dailyRegulations"
-                ]["timeToPlayInOneDay"]["limitTime"] = minutes
+                self.parental_control_settings["playTimerRegulations"]["dailyRegulations"]["timeToPlayInOneDay"][
+                    "limitTime"
+                ] = minutes
         else:
             _LOGGER.debug(
                 "Setting timeToPlayInOneDay.limitTime for device %s to value %s",
                 self.device_id,
                 minutes,
             )
-            day_of_week_regs = self.parental_control_settings["playTimerRegulations"][
-                "eachDayOfTheWeekRegulations"
-            ]
+            day_of_week_regs = self.parental_control_settings["playTimerRegulations"]["eachDayOfTheWeekRegulations"]
             current_day = DAYS_OF_WEEK[now.weekday()]
             day_of_week_regs[current_day]["timeToPlayInOneDay"]["enabled"] = ttpiod
-            if (
-                "limitTime" in day_of_week_regs[current_day]["timeToPlayInOneDay"]
-                and minutes is None
-            ):
+            if "limitTime" in day_of_week_regs[current_day]["timeToPlayInOneDay"] and minutes is None:
                 day_of_week_regs[current_day]["timeToPlayInOneDay"].pop("limitTime")
             else:
-                day_of_week_regs[current_day]["timeToPlayInOneDay"]["limitTime"] = (
-                    minutes
-                )
+                day_of_week_regs[current_day]["timeToPlayInOneDay"]["limitTime"] = minutes
 
         await self._send_api_update(
             self._api.async_update_play_timer,
@@ -411,52 +594,62 @@ class Device:
     def _get_today_regulation(self, now: datetime) -> dict:
         """Returns the regulation settings for the current day."""
         if self.timer_mode == DeviceTimerMode.EACH_DAY_OF_THE_WEEK:
-            day_of_week_regs = self.parental_control_settings[
-                "playTimerRegulations"
-            ].get("eachDayOfTheWeekRegulations", {})
+            day_of_week_regs = self.parental_control_settings["playTimerRegulations"].get(
+                "eachDayOfTheWeekRegulations", {}
+            )
             return day_of_week_regs.get(DAYS_OF_WEEK[now.weekday()], {})
-        return self.parental_control_settings.get("playTimerRegulations", {}).get(
-            "dailyRegulations", {}
-        )
+        return self.parental_control_settings.get("playTimerRegulations", {}).get("dailyRegulations", {})
 
     def _parse_parental_control_setting(self, pcs: dict, now: datetime):
         """Parse a parental control setting request response."""
         _LOGGER.debug(">> Device._parse_parental_control_setting()")
         self.parental_control_settings = pcs["parentalControlSetting"]
-        self.parental_control_settings["playTimerRegulations"].pop(
-            "bedtimeStartingTime", None
+        self.parental_control_settings["playTimerRegulations"].pop("bedtimeStartingTime", None)
+        self.parental_control_settings["playTimerRegulations"].pop("bedtimeEndingTime", None)
+        self.forced_termination_mode = self.parental_control_settings["playTimerRegulations"]["restrictionMode"] == str(
+            RestrictionMode.FORCED_TERMINATION
         )
-        self.parental_control_settings["playTimerRegulations"].pop(
-            "bedtimeEndingTime", None
-        )
-        self.forced_termination_mode = self.parental_control_settings[
-            "playTimerRegulations"
-        ]["restrictionMode"] == str(RestrictionMode.FORCED_TERMINATION)
 
         # Update limit and bedtime from regulations
-        self.timer_mode = DeviceTimerMode(
-            self.parental_control_settings["playTimerRegulations"]["timerMode"]
-        )
+        self.timer_mode = DeviceTimerMode(self.parental_control_settings["playTimerRegulations"]["timerMode"])
         today_reg = self._get_today_regulation(now)
         limit_time = today_reg.get("timeToPlayInOneDay", {}).get("limitTime")
         self.limit_time = limit_time if limit_time is not None else -1
-        extra_playing_time_data = (
-            pcs.get("ownedDevice", {}).get("device", {}).get("extraPlayingTime")
-        )
-        self.extra_playing_time = None
-        if extra_playing_time_data:
-            self.extra_playing_time = extra_playing_time_data.get("inOneDay", {}).get(
-                "duration"
-            )
-
         bedtime_setting = today_reg.get("bedtime", {})
-        if bedtime_setting.get("enabled") and bedtime_setting["endingTime"]:
+        bedtime_enabled = bedtime_setting.get("enabled", False)
+
+        # Set bedtime_alarm first as we need it for extra_playing_time calculation
+        if bedtime_enabled and bedtime_setting.get("endingTime"):
             self.bedtime_alarm = time(
                 hour=bedtime_setting["endingTime"]["hour"],
                 minute=bedtime_setting["endingTime"]["minute"],
             )
         else:
             self.bedtime_alarm = time(hour=0, minute=0)
+
+        # Parse extra playing time based on whether bedtime is enabled
+        extra_playing_time_data = pcs.get("ownedDevice", {}).get("device", {}).get("extraPlayingTime")
+        self.extra_playing_time = None
+        if extra_playing_time_data is not None:
+            if bedtime_enabled and extra_playing_time_data.get("bedtime"):
+                # When bedtime is enabled, calculate the difference between new bedtime and original bedtime
+                extended_bedtime_data = extra_playing_time_data.get("bedtime", {}).get("endTime")
+                if extended_bedtime_data:
+                    extended_bedtime = time(
+                        hour=extended_bedtime_data["hour"],
+                        minute=extended_bedtime_data["minute"],
+                    )
+                    # Calculate difference in minutes
+                    original_minutes = self.bedtime_alarm.hour * 60 + self.bedtime_alarm.minute
+                    extended_minutes = extended_bedtime.hour * 60 + extended_bedtime.minute
+                    self.extra_playing_time = extended_minutes - original_minutes
+                    # Update bedtime_alarm to the extended bedtime
+                    self.bedtime_alarm = extended_bedtime
+            else:
+                # When bedtime is disabled, use inOneDay duration
+                in_one_day = extra_playing_time_data.get("inOneDay")
+                if in_one_day is not None:
+                    self.extra_playing_time = in_one_day.get("duration")
         if bedtime_setting.get("enabled") and bedtime_setting["startingTime"]:
             self.bedtime_end = time(
                 hour=bedtime_setting["startingTime"]["hour"],
@@ -505,32 +698,26 @@ class Device:
 
             if self.limit_time in (-1, None):
                 # No play limit, so remaining time is until end of day.
-                time_remaining_by_play_limit = (
-                    minutes_in_day - current_minutes_past_midnight
-                )
+                time_remaining_by_play_limit = minutes_in_day - current_minutes_past_midnight
             else:
-                time_remaining_by_play_limit = self.limit_time - self.today_playing_time
+                # Calculate remaining time from play limit, adding any extra playing time
+                effective_limit = self.limit_time
+                if self.extra_playing_time:
+                    effective_limit += self.extra_playing_time
+                time_remaining_by_play_limit = effective_limit - self.today_playing_time
 
             # 2. Calculate remaining time until bedtime
-            if (
-                self.bedtime_alarm
-                and self.bedtime_alarm != time(hour=0, minute=0)
-                and self.alarms_enabled
-            ):
+            if self.bedtime_alarm and self.bedtime_alarm != time(hour=0, minute=0) and self.alarms_enabled:
                 bedtime_dt = datetime.combine(now.date(), self.bedtime_alarm)
                 if bedtime_dt > now:  # Bedtime is in the future today
                     time_remaining_by_bedtime = (bedtime_dt - now).total_seconds() / 60
                 else:  # Bedtime has passed
                     time_remaining_by_bedtime = 0.0
             else:
-                time_remaining_by_bedtime = (
-                    minutes_in_day - current_minutes_past_midnight
-                )
+                time_remaining_by_bedtime = minutes_in_day - current_minutes_past_midnight
 
             # Effective remaining time is the minimum of the two constraints
-            effective_remaining_time = min(
-                time_remaining_by_play_limit, time_remaining_by_bedtime
-            )
+            effective_remaining_time = min(time_remaining_by_play_limit, time_remaining_by_bedtime)
             self.today_time_remaining = int(max(0.0, effective_remaining_time))
             _LOGGER.debug(
                 "Calculated today's remaining time: %s minutes",
@@ -538,25 +725,19 @@ class Device:
             )
             self.stats_update_failed = False
         except (ValueError, TypeError, AttributeError) as err:
-            _LOGGER.warning(
-                "Unable to calculate remaining time for device %s: %s", self.name, err
-            )
+            _LOGGER.warning("Unable to calculate remaining time for device %s: %s", self.name, err)
 
     async def _get_parental_control_setting(self, now: datetime):
         """Retreives parental control settings from the API."""
         _LOGGER.debug(">> Device._get_parental_control_setting()")
-        response = await self._api.async_get_device_parental_control_setting(
-            device_id=self.device_id
-        )
+        response = await self._api.async_get_device_parental_control_setting(device_id=self.device_id)
         self._parse_parental_control_setting(response["json"], now)
         self._calculate_times(now)
 
     async def _get_daily_summaries(self, now: datetime):
         """Retrieve daily summaries."""
         _LOGGER.debug(">> Device._get_daily_summaries()")
-        response = await self._api.async_get_device_daily_summaries(
-            device_id=self.device_id
-        )
+        response = await self._api.async_get_device_daily_summaries(device_id=self.device_id)
         self.daily_summaries = response["json"]["dailySummaries"]
         _LOGGER.debug("New daily summary %s", self.daily_summaries)
         self._calculate_times(now)
@@ -566,9 +747,7 @@ class Device:
         _LOGGER.debug(">> Device._get_extras()")
         if self.alarms_enabled is not None:
             # first refresh can come from self.extra without http request
-            response = await self._api.async_get_account_device(
-                device_id=self.device_id
-            )
+            response = await self._api.async_get_account_device(device_id=self.device_id)
             self.extra = response["json"]["ownedDevice"]["device"]
         status = self.extra["alarmSetting"]["visibility"]
         self.alarms_enabled = status == str(AlarmSettingState.VISIBLE)
@@ -579,14 +758,30 @@ class Device:
         )
 
     async def get_monthly_summary(self, search_date: datetime = None) -> dict | None:
-        """Gets the monthly summary."""
+        """Get the monthly usage summary for a specific month.
+
+        Args:
+            search_date: The month to get the summary for. If None, returns the most recent available summary.
+
+        Returns:
+            Dictionary containing monthly usage data, or None if no summary is available.
+
+        Example:
+            ```python
+            from datetime import datetime
+
+            # Get summary for January 2024
+            summary = await device.get_monthly_summary(datetime(2024, 1, 1))
+
+            # Get most recent summary
+            summary = await device.get_monthly_summary()
+            ```
+        """
         _LOGGER.debug(">> Device.get_monthly_summary(search_date=%s)", search_date)
         latest = False
         if search_date is None:
             try:
-                response = await self._api.async_get_device_monthly_summaries(
-                    device_id=self.device_id
-                )
+                response = await self._api.async_get_device_monthly_summaries(device_id=self.device_id)
             except HttpException as exc:
                 _LOGGER.debug("Could not retrieve monthly summaries: %s", exc)
                 return
@@ -594,9 +789,7 @@ class Device:
                 available_summaries = response["json"]["available"]
                 _LOGGER.debug("Available monthly summaries: %s", available_summaries)
                 if not available_summaries:
-                    _LOGGER.debug(
-                        "No monthly summaries available for device %s", self.device_id
-                    )
+                    _LOGGER.debug("No monthly summaries available for device %s", self.device_id)
                     return None
                 # Use the most recent available summary
                 available_summary = available_summaries[0]
@@ -604,9 +797,7 @@ class Device:
                     f"{available_summary['year']}-{available_summary['month']}-01",
                     "%Y-%m-%d",
                 )
-                _LOGGER.debug(
-                    "Using search date %s for monthly summary request", search_date
-                )
+                _LOGGER.debug("Using search date %s for monthly summary request", search_date)
                 latest = True
 
         try:
@@ -629,9 +820,7 @@ class Device:
             if latest:
                 self.last_month_summary = summary = response["json"]["summary"]
                 # Generate player objects
-                for player in (
-                    response.get("json", {}).get("summary", {}).get("players", [])
-                ):
+                for player in response.get("json", {}).get("summary", {}).get("players", []):
                     profile = player.get("profile")
                     if not profile or not profile.get("playerId"):
                         continue
@@ -643,42 +832,85 @@ class Device:
             return response["json"]["summary"]
 
     def get_date_summary(self, input_date: datetime = datetime.now()) -> dict:
-        """Returns usage for a given date."""
+        """Get the usage summary for a specific date.
+
+        Args:
+            input_date: The date to get the summary for. Defaults to today.
+
+        Returns:
+            Dictionary containing usage data for the specified date.
+
+        Raises:
+            ValueError: If no summary exists for the given date or no summaries are available.
+
+        Example:
+            ```python
+            from datetime import datetime, timedelta
+
+            # Get today's summary
+            today = device.get_date_summary()
+
+            # Get yesterday's summary
+            yesterday = device.get_date_summary(datetime.now() - timedelta(days=1))
+            ```
+        """
         if not self.daily_summaries:
             raise ValueError("No daily summaries available to search.")
-        summary = [
-            x
-            for x in self.daily_summaries
-            if x["date"] == input_date.strftime("%Y-%m-%d")
-        ]
+        summary = [x for x in self.daily_summaries if x["date"] == input_date.strftime("%Y-%m-%d")]
         if len(summary) == 0:
             input_date -= timedelta(days=1)
-            summary = [
-                x
-                for x in self.daily_summaries
-                if x["date"] == input_date.strftime("%Y-%m-%d")
-            ]
+            summary = [x for x in self.daily_summaries if x["date"] == input_date.strftime("%Y-%m-%d")]
         if len(summary) == 0:
-            raise ValueError(
-                f"A summary for the given date {input_date} does not exist"
-            )
+            raise ValueError(f"A summary for the given date {input_date} does not exist")
         return summary
 
     def get_application(self, application_id: str) -> Application:
-        """Returns a single application."""
+        """Get an Application object by its application ID.
+
+        Args:
+            application_id: The unique identifier for the application.
+
+        Returns:
+            The Application object for the specified ID.
+
+        Raises:
+            ValueError: If the application is not found.
+
+        Example:
+            ```python
+            app = device.get_application("0100ABC001234000")
+            print(f"Application: {app.name}")
+            ```
+        """
         if application_id in self.applications:
             return self.applications[application_id]
         raise ValueError(f"Application with id {application_id} not found.")
 
     def get_player(self, player_id: str) -> Player:
-        """Returns a player."""
+        """Get a Player object by player ID.
+
+        Args:
+            player_id: The unique identifier for the player.
+
+        Returns:
+            The Player object for the specified ID.
+
+        Raises:
+            ValueError: If the player is not found.
+
+        Example:
+            ```python
+            player = device.get_player("player123")
+            print(f"Player: {player.nickname}")
+            ```
+        """
         player = self.players.get(player_id)
         if player:
             return player
         raise ValueError(f"Player with id {player_id} not found.")
 
     @classmethod
-    async def from_devices_response(cls, raw: dict, api) -> list["Device"]:
+    async def from_devices_response(cls, raw: dict, api, now: datetime = None) -> list["Device"]:
         """Parses a device request response body."""
         _LOGGER.debug("Parsing device list response")
         if "ownedDevices" not in raw.keys():
@@ -690,7 +922,7 @@ class Device:
             parsed.name = device["label"]
             parsed.sync_state = device["parentalControlSettingState"]["updatedAt"]
             parsed.extra = device
-            await parsed.update()
+            await parsed.update(now=now)
             devices.append(parsed)
 
         return devices