From 3bedd80c605ff2b64eea8a940a9a150c296e2a7a Mon Sep 17 00:00:00 2001
From: jxxghp <jxxghp@gmail.com>
Date: Fri, 16 Oct 2026 23:49:30 +0800
Subject: [PATCH] refactor(types): govern TMDb configuration response contract

---
 .../tmdbv3api/objs/configuration.py           | 31 ++++++++++---------
 mypy.ini                                      |  1 +
 2 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/app/modules/themoviedb/tmdbv3api/objs/configuration.py b/app/modules/themoviedb/tmdbv3api/objs/configuration.py
index c0c0cdc0b..de08854cb 100644
--- a/app/modules/themoviedb/tmdbv3api/objs/configuration.py
+++ b/app/modules/themoviedb/tmdbv3api/objs/configuration.py
@@ -1,9 +1,11 @@
 import warnings
 
-from ..tmdb import TMDb
+from ..tmdb import TMDb, TMDbJson
 
 
 class Configuration(TMDb):
+    """提供 TMDb 系统配置查询及旧接口兼容入口。"""
+
     _urls = {
         "api_configuration": "/configuration",
         "countries": "/configuration/countries",
@@ -13,79 +15,80 @@ class Configuration(TMDb):
         "timezones": "/configuration/timezones"
     }
 
-    def info(self):
+    def info(self) -> TMDbJson:
+        """保留旧配置入口及其弃用告警。"""
         warnings.warn("info method is deprecated use tmdbv3api.Configuration().api_configuration()",
                       DeprecationWarning)
         return self.api_configuration()
 
-    def api_configuration(self):
+    def api_configuration(self) -> TMDbJson:
         """
         Get the system wide configuration info.
         """
         return self._request_obj(self._urls["api_configuration"])
 
-    def countries(self):
+    def countries(self) -> TMDbJson:
         """
         Get the list of countries (ISO 3166-1 tags) used throughout TMDb.
         """
         return self._request_obj(self._urls["countries"])
 
-    def jobs(self):
+    def jobs(self) -> TMDbJson:
         """
         Get a list of the jobs and departments we use on TMDb.
         """
         return self._request_obj(self._urls["jobs"])
 
-    def languages(self):
+    def languages(self) -> TMDbJson:
         """
         Get the list of languages (ISO 639-1 tags) used throughout TMDb.
         """
         return self._request_obj(self._urls["languages"])
 
-    def primary_translations(self):
+    def primary_translations(self) -> TMDbJson:
         """
         Get a list of the officially supported translations on TMDb.
         """
         return self._request_obj(self._urls["primary_translations"])
 
-    def timezones(self):
+    def timezones(self) -> TMDbJson:
         """
         Get the list of timezones used throughout TMDb.
         """
         return self._request_obj(self._urls["timezones"])
 
     # 异步版本方法
-    async def async_api_configuration(self):
+    async def async_api_configuration(self) -> TMDbJson:
         """
         Get the system wide configuration info.（异步版本）
         """
         return await self._async_request_obj(self._urls["api_configuration"])
 
-    async def async_countries(self):
+    async def async_countries(self) -> TMDbJson:
         """
         Get the list of countries (ISO 3166-1 tags) used throughout TMDb.（异步版本）
         """
         return await self._async_request_obj(self._urls["countries"])
 
-    async def async_jobs(self):
+    async def async_jobs(self) -> TMDbJson:
         """
         Get a list of the jobs and departments we use on TMDb.（异步版本）
         """
         return await self._async_request_obj(self._urls["jobs"])
 
-    async def async_languages(self):
+    async def async_languages(self) -> TMDbJson:
         """
         Get the list of languages (ISO 639-1 tags) used throughout TMDb.（异步版本）
         """
         return await self._async_request_obj(self._urls["languages"])
 
-    async def async_primary_translations(self):
+    async def async_primary_translations(self) -> TMDbJson:
         """
         Get a list of the officially supported translations on TMDb.（异步版本）
         """
         return await self._async_request_obj(self._urls["primary_translations"])
 
-    async def async_timezones(self):
+    async def async_timezones(self) -> TMDbJson:
         """
         Get the list of timezones used throughout TMDb.（异步版本）
         """
diff --git a/mypy.ini b/mypy.ini
index 48cc91abd..68787c6fc 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -177,4 +177,5 @@ files =
     app/modules/themoviedb/tmdbv3api/objs/list.py,
     app/modules/themoviedb/tmdbv3api/objs/genre.py,
     app/modules/themoviedb/tmdbv3api/objs/certification.py,
+    app/modules/themoviedb/tmdbv3api/objs/configuration.py,
     scripts/architecture/async_blocking.py