pynintendoparental 2.3.2__tar.gz → 2.3.2.1__tar.gz

{pynintendoparental-2.3.2 → pynintendoparental-2.3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pynintendoparental
-Version: 2.3.2
+Version: 2.3.2.1
 Summary: A Python module to interact with Nintendo Parental Controls
 Home-page: http://github.com/pantherale0/pynintendoparental
 Author: pantherale0
@@ -16,7 +16,7 @@ Provides-Extra: dev
 Requires-Dist: aiofiles<26,>=23; extra == "dev"
 Requires-Dist: bandit<1.10,>=1.7; extra == "dev"
 Requires-Dist: black<26,>=23; extra == "dev"
-Requires-Dist: build<1.4,>=0.10; extra == "dev"
+Requires-Dist: build<1.5,>=0.10; extra == "dev"
 Requires-Dist: Faker<41,>=38; extra == "dev"
 Requires-Dist: flake8<8,>=6; extra == "dev"
 Requires-Dist: isort<8,>=5; extra == "dev"

{pynintendoparental-2.3.2 → pynintendoparental-2.3.2.1}/pynintendoparental/__init__.py

@@ -6,14 +6,22 @@ import asyncio
 from pynintendoauth.exceptions import HttpException
 
 from .api import Api
+from .authenticator import Authenticator
 from .const import _LOGGER
 from .device import Device
 from .exceptions import NoDevicesFoundException
-from .authenticator import Authenticator
 
 
 class NintendoParental:
-    """Core Python API."""
+    """Core Python API for Nintendo Switch Parental Controls.
+
+    This is the main entry point for interacting with Nintendo Switch Parental Controls.
+    Use the `create` class method to instantiate this class.
+
+    Attributes:
+        account_id: The Nintendo account ID.
+        devices: Dictionary of Device objects keyed by device ID.
+    """
 
     def __init__(self, auth: Authenticator, timezone, lang) -> None:
         self._api: Api = Api(auth=auth, tz=timezone, lang=lang)
@@ -48,7 +56,12 @@ class NintendoParental:
         _LOGGER.debug("Found %s device(s)", len(self.devices))
 
     async def update(self):
-        """Update module data."""
+        """Update module data.
+
+        Refreshes all devices and their associated data from Nintendo's servers.
+        This method fetches the latest information about all devices linked to
+        the authenticated account.
+        """
         _LOGGER.debug("Received request to update data.")
         await self._get_devices()
         _LOGGER.debug("Update complete.")
@@ -57,7 +70,29 @@ class NintendoParental:
     async def create(
         cls, auth: Authenticator, timezone: str = "Europe/London", lang: str = "en-GB"
     ) -> "NintendoParental":
-        """Create an instance of NintendoParental."""
+        """Create an instance of NintendoParental.
+
+        This is the recommended way to create a NintendoParental instance as it
+        handles the asynchronous initialization and fetches initial device data.
+
+        Args:
+            auth: An authenticated Authenticator instance.
+            timezone: The timezone to use for API requests (default: "Europe/London").
+                     Use any valid IANA timezone identifier.
+            lang: The language code for API responses (default: "en-GB").
+                  Use ISO 639-1 language codes with ISO 3166-1 country codes.
+
+        Returns:
+            A fully initialized NintendoParental instance with device data loaded.
+
+        Example:
+            ```python
+            async with aiohttp.ClientSession() as session:
+                auth = Authenticator(session_token, session)
+                await auth.async_complete_login(use_session_token=True)
+                nintendo = await NintendoParental.create(auth, timezone="America/New_York", lang="en-US")
+            ```
+        """
         self = cls(auth, timezone, lang)
         await self.update()
         return self

pynintendoparental-2.3.2.1/pynintendoparental/_version.py

@@ -0,0 +1 @@
+__version__ = "2.3.2.1"

{pynintendoparental-2.3.2 → pynintendoparental-2.3.2.1}/pynintendoparental/api.py

@@ -1,21 +1,20 @@
 """API handler."""
 
 import aiohttp
-
 from pynintendoauth.exceptions import HttpException
 
 from .authenticator import Authenticator
 from .const import (
-    ENDPOINTS,
+    _LOGGER,
     BASE_URL,
-    USER_AGENT,
-    MOBILE_APP_PKG,
+    DEVICE_MODEL,
+    ENDPOINTS,
     MOBILE_APP_BUILD,
+    MOBILE_APP_PKG,
     MOBILE_APP_VERSION,
-    OS_VERSION,
     OS_NAME,
-    DEVICE_MODEL,
-    _LOGGER,
+    OS_VERSION,
+    USER_AGENT,
 )
 
 
@@ -80,9 +79,7 @@ class Api:
                 try:
                     error: dict = await response.json()
                     if "detail" in error:
-                        raise HttpException(
-                            response.status, error["detail"], error.get("errorCode")
-                        )
+                        raise HttpException(response.status, error["detail"], error.get("errorCode"))
                 except (aiohttp.ContentTypeError, ValueError):
                     # Fall through to the generic exception below on parsing failure.
                     pass
@@ -114,31 +111,21 @@ class Api:
 
     async def async_get_account_device(self, device_id: str) -> dict:
         """Get account device."""
-        return await self.send_request(
-            endpoint="get_account_device", DEVICE_ID=device_id
-        )
+        return await self.send_request(endpoint="get_account_device", DEVICE_ID=device_id)
 
     async def async_get_device_daily_summaries(self, device_id: str) -> dict:
         """Get device daily summaries."""
-        return await self.send_request(
-            endpoint="get_device_daily_summaries", DEVICE_ID=device_id
-        )
+        return await self.send_request(endpoint="get_device_daily_summaries", DEVICE_ID=device_id)
 
     async def async_get_device_monthly_summaries(self, device_id: str) -> dict:
         """Get device monthly summaries."""
-        return await self.send_request(
-            endpoint="get_device_monthly_summaries", DEVICE_ID=device_id
-        )
+        return await self.send_request(endpoint="get_device_monthly_summaries", DEVICE_ID=device_id)
 
     async def async_get_device_parental_control_setting(self, device_id: str) -> dict:
         """Get device parental control setting."""
-        return await self.send_request(
-            endpoint="get_device_parental_control_setting", DEVICE_ID=device_id
-        )
+        return await self.send_request(endpoint="get_device_parental_control_setting", DEVICE_ID=device_id)
 
-    async def async_get_device_monthly_summary(
-        self, device_id: str, year: int, month: int
-    ) -> dict:
+    async def async_get_device_monthly_summary(self, device_id: str, year: int, month: int) -> dict:
         """Get device monthly summary."""
         return await self.send_request(
             endpoint="get_device_monthly_summary",
@@ -147,9 +134,7 @@ class Api:
             MONTH=f"{month:02d}",
         )
 
-    async def async_update_restriction_level(
-        self, device_id: str, parental_control_setting: dict
-    ) -> dict:
+    async def async_update_restriction_level(self, device_id: str, parental_control_setting: dict) -> dict:
         """Update device restriction level."""
         allowed_keys = (
             "whitelistedApplicationList",
@@ -159,18 +144,12 @@ class Api:
             "deviceId": device_id,
             "customSettings": parental_control_setting.get("customSettings", {}),
             "parentalControlSettingEtag": parental_control_setting.get("etag"),
-            "vrRestrictionEtag": parental_control_setting.get("customSettings", {}).get(
-                "vrRestrictionEtag"
-            ),
+            "vrRestrictionEtag": parental_control_setting.get("customSettings", {}).get("vrRestrictionEtag"),
             **{key: parental_control_setting.get(key) for key in allowed_keys},
         }
-        return await self.send_request(
-            endpoint="update_restriction_level", body=settings
-        )
+        return await self.send_request(endpoint="update_restriction_level", body=settings)
 
-    async def async_update_play_timer(
-        self, device_id: str, play_timer_regulations: dict
-    ) -> dict:
+    async def async_update_play_timer(self, device_id: str, play_timer_regulations: dict) -> dict:
         """Update device play timer settings."""
         allowed_ptr_keys = (
             "timerMode",
@@ -180,9 +159,7 @@ class Api:
         )
         settings = {
             "deviceId": device_id,
-            "playTimerRegulations": {
-                key: play_timer_regulations.get(key) for key in allowed_ptr_keys
-            },
+            "playTimerRegulations": {key: play_timer_regulations.get(key) for key in allowed_ptr_keys},
         }
         return await self.send_request(endpoint="update_play_timer", body=settings)
 
@@ -193,9 +170,7 @@ class Api:
             body={"deviceId": device_id, "unlockCode": str(new_code)},
         )
 
-    async def async_update_extra_playing_time(
-        self, device_id: str, additional_time: int
-    ) -> dict:
+    async def async_update_extra_playing_time(self, device_id: str, additional_time: int) -> dict:
         """Update device extra playing time."""
         body = {
             "deviceId": device_id,

{pynintendoparental-2.3.2 → pynintendoparental-2.3.2.1}/pynintendoparental/application.py

@@ -2,7 +2,7 @@
 
 import copy
 from datetime import datetime
-from typing import Callable, TYPE_CHECKING
+from typing import TYPE_CHECKING, Callable
 
 from .api import Api
 from .const import _LOGGER
@@ -14,7 +14,20 @@ if TYPE_CHECKING:
 
 
 class Application:
-    """Model for an application"""
+    """A Nintendo Switch game or application.
+
+    Represents a game or application on a Nintendo Switch console with parental control settings.
+
+    Attributes:
+        application_id: Unique identifier for the application.
+        name: Display name of the application.
+        image_url: URL to the application's icon image.
+        safe_launch_setting: Whether the app is on the Allow List (bypasses age restrictions).
+        today_time_played: Total time played today across all players in minutes.
+        first_played_date: Date when the application was first played.
+        playing_days: Number of days the application has been played.
+        shop_url: URL to the application in the Nintendo eShop.
+    """
 
     def __init__(
         self,
@@ -48,11 +61,27 @@ class Application:
         callbacks.append(self._internal_update_callback)
 
     async def set_safe_launch_setting(self, safe_launch_setting: SafeLaunchSetting):
-        """Set the safe launch setting for the application."""
-        if (
-            not self._device
-            or "whitelistedApplicationList" not in self._parental_control_settings
-        ):
+        """Set the application's status on the Allow List.
+
+        Applications on the Allow List can bypass general age/content restrictions.
+
+        Args:
+            safe_launch_setting: The setting to apply. Options are:
+                - SafeLaunchSetting.NONE: Remove from Allow List (apply normal restrictions).
+                - SafeLaunchSetting.ALLOW: Add to Allow List (bypass restrictions).
+
+        Raises:
+            ValueError: If the application data is not properly initialized.
+            LookupError: If the application is no longer in the whitelist.
+
+        Example:
+            ```python
+            from pynintendoparental.enum import SafeLaunchSetting
+
+            await app.set_safe_launch_setting(SafeLaunchSetting.ALLOW)
+            ```
+        """
+        if not self._device or "whitelistedApplicationList" not in self._parental_control_settings:
             raise ValueError("Unable to set SafeLaunchSetting, callbacks not executed.")
         # Update the application safe_launch_setting in the PCS
         pcs = copy.deepcopy(self._parental_control_settings)
@@ -61,9 +90,7 @@ class Application:
                 app["safeLaunch"] = str(safe_launch_setting)
                 break
         else:
-            raise LookupError(
-                "Unable to set SafeLaunchSetting, application no longer in whitelist."
-            )
+            raise LookupError("Unable to set SafeLaunchSetting, application no longer in whitelist.")
 
         await self._send_api_update(
             self._api.async_update_restriction_level,
@@ -92,23 +119,16 @@ class Application:
                 device.device_id,
                 self.application_id,
             )
-        for app in self._parental_control_settings.get(
-            "whitelistedApplicationList", []
-        ):
+        for app in self._parental_control_settings.get("whitelistedApplicationList", []):
             if app["applicationId"].upper() == self.application_id.upper():
-                self.safe_launch_setting = SafeLaunchSetting(
-                    app.get("safeLaunch", "NONE")
-                )
+                self.safe_launch_setting = SafeLaunchSetting(app.get("safeLaunch", "NONE"))
                 self.image_url = app["imageUri"]
                 break
         total_time_played: int = 0
         if self._daily_summary:
             for player_summary in self._daily_summary[0].get("players", []):
                 for player_app in player_summary.get("playedGames", []):
-                    if (
-                        player_app["meta"]["applicationId"].upper()
-                        == self.application_id.upper()
-                    ):
+                    if player_app["meta"]["applicationId"].upper() == self.application_id.upper():
                         total_time_played += player_app["playingTime"]
                         break
         self.today_time_played = total_time_played
@@ -119,14 +139,36 @@ class Application:
             else:
                 cb(self)
 
-    def add_application_callback(self, callback):
-        """Add a callback to the application."""
+    def add_application_callback(self, callback: Callable):
+        """Add a callback function to be called when application state changes.
+
+        Args:
+            callback: A callable function. Can be sync or async.
+
+        Raises:
+            ValueError: If the provided object is not callable.
+
+        Example:
+            ```python
+            async def on_app_update(app):
+                print(f"App {app.name} updated!")
+
+            app.add_application_callback(on_app_update)
+            ```
+        """
         if not callable(callback):
             raise ValueError("Object must be callable.")
         self._callbacks.append(callback)
 
-    def remove_application_callback(self, callback):
-        """Remove a callback from the application."""
+    def remove_application_callback(self, callback: Callable):
+        """Remove a previously registered application callback.
+
+        Args:
+            callback: The callback function to remove.
+
+        Raises:
+            ValueError: If the callback is not found.
+        """
         if callback not in self._callbacks:
             raise ValueError("Callback not found.")
         self._callbacks.remove(callback)

pynintendoparental-2.3.2.1/pynintendoparental/authenticator.py

@@ -0,0 +1,44 @@
+"""Nintendo Authentication."""
+
+from __future__ import annotations
+
+from pynintendoauth import NintendoAuth
+
+from .const import CLIENT_ID
+
+
+class Authenticator(NintendoAuth):
+    """Nintendo authentication handler.
+
+    Handles authentication with Nintendo's servers for accessing Parental Controls API.
+    Supports both session token and interactive login methods.
+
+    Attributes:
+        session_token: The session token for authentication.
+        account_id: The authenticated Nintendo account ID.
+        login_url: URL for interactive login (when session_token not provided).
+
+    Example:
+        Using a session token:
+        ```python
+        async with aiohttp.ClientSession() as session:
+            auth = Authenticator(session_token="YOUR_TOKEN", client_session=session)
+            await auth.async_complete_login(use_session_token=True)
+        ```
+
+        Interactive login:
+        ```python
+        async with aiohttp.ClientSession() as session:
+            auth = Authenticator(client_session=session)
+            print(f"Visit: {auth.login_url}")
+            response_url = input("Paste redirect URL: ")
+            await auth.async_complete_login(response_url)
+        ```
+    """
+
+    def __init__(self, session_token=None, client_session=None):
+        super().__init__(
+            client_id=CLIENT_ID,
+            session_token=session_token,
+            client_session=client_session,
+        )

{pynintendoparental-2.3.2 → pynintendoparental-2.3.2.1}/pynintendoparental/const.py

@@ -59,7 +59,9 @@ ENDPOINTS = {
         "method": "POST",
     },
     "get_device_monthly_summary": {
-        "url": "{BASE_URL}/v2/actions/playSummary/fetchMonthlySummary?deviceId={DEVICE_ID}&year={YEAR}&month={MONTH}&containLatest=false",
+        "url": (
+            "{BASE_URL}/v2/actions/playSummary/fetchMonthlySummary?deviceId={DEVICE_ID}&year={YEAR}&month={MONTH}&containLatest=false"
+        ),
         "method": "GET",
     },
     "update_extra_playing_time": {