aioqzone 1.9.6.dev6__tar.gz → 1.9.8.dev1__tar.gz

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aioqzone
-Version: 1.9.6.dev6
+Version: 1.9.8.dev1
 Summary: A Python wrapper for Qzone login and H5 APIs.
 Keywords: qzone-api,autologin,asyncio-spider
 Author: aioqzone
@@ -9,7 +9,7 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Dist: aiohttp~=3.13
+Requires-Dist: aiohttp~=3.14
 Requires-Dist: pydantic~=2.12
 Requires-Dist: pydantic-settings>=2.9.0
 Requires-Dist: rsa>=4.9.1

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aioqzone"
-version = "1.9.6.dev6"
+version = "1.9.8.dev1"
 description = "A Python wrapper for Qzone login and H5 APIs."
 authors = [{ name = "aioqzone" }]
 maintainers = [
@@ -18,7 +18,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "aiohttp~=3.13",
+    "aiohttp~=3.14",
     "pydantic~=2.12",
     "pydantic-settings>=2.9.0",
     "rsa>=4.9.1",

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/src/aioqzone/api/__init__.py

@@ -1,3 +1,9 @@
+"""aioqzone API package.
+
+Exports :class:`QrLoginConfig`, :class:`UpLoginConfig`, :class:`Loginable`,
+and :class:`QzoneH5API`.
+"""
+
 from .h5 import QzoneH5API
 from .login import *
 from .login._base import Loginable

aioqzone-1.9.8.dev1/src/aioqzone/api/h5/__init__.py

@@ -0,0 +1,8 @@
+"""H5 API subpackage.
+
+Exports :class:`QzoneH5API`.
+"""
+
+from .model import QzoneH5API
+
+__all__ = ["QzoneH5API"]

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/src/aioqzone/api/h5/model.py

@@ -1,3 +1,9 @@
+"""Qzone H5 API client.
+
+Defines :class:`QzoneH5API` — the main API entry point for all Qzone H5
+operations including feed fetching, commenting, liking, and photo upload.
+"""
+
 import logging
 import typing as t
 from os import PathLike
@@ -14,12 +20,22 @@ log = logging.getLogger(__name__)
 
 
 class QzoneH5API:
+    """Main Qzone H5 API client.
+
+    Wraps Qzone HTTP endpoints behind typed API methods. Handles login
+    state, automatic token injection, and retry-on-login-expire logic.
+    All methods delegate to :meth:`call` for actual HTTP dispatch.
+    """
+
     qzone_tokens: t.Dict[int, str]
+    """Cached qzonetokens keyed by host uin."""
 
     def __init__(
         self, client: ClientAdapter, loginman: Loginable, *, retry_if_login_expire: bool = True
     ) -> None:
         """
+        :param client: network client
+        :param loginman: login manager
         :param retry_if_login_expire: if we should retry if login expired.
         """
         super().__init__()
@@ -47,6 +63,16 @@ class QzoneH5API:
         self.qzone_tokens = {}
 
     async def call(self, api: QzoneApi[TyRequest, TyResponse]) -> TyResponse:
+        """Execute an API call with full lifecycle management.
+
+        Builds params, injects authentication (g_tk, qzonetoken, cookies),
+        dispatches HTTP request, parses response, and handles retry on
+        login expiry.
+
+        :param api: the API definition to call
+        :returns: typed response object
+        :raises RuntimeError: if max retry exceeded
+        """
         params: t.Dict[str, t.Any] = api.params.build_params(self.login.uin)
         if api.http_method == "GET":
             data = {}
@@ -89,7 +115,7 @@ class QzoneH5API:
                         log.debug(f"Error when validating {obj}, {api=}")
                         raise
         else:
-            raise AssertionError
+            raise RuntimeError("max retry exceeded")
 
     async def _retry_sleep(self, *_) -> None:
         await self.login.new_cookie()
@@ -97,7 +123,7 @@ class QzoneH5API:
     async def index(self) -> IndexPageResp:
         """This api is the redirect page after h5 login, which is also the landing (main) page of h5 qzone.
 
-        :raise `RuntimeError`: if any failure occurs in data parsing.
+        :raise `RuntimeError`: if max retry exceeded.
         """
 
         r = await self.call(IndexPageApi())
@@ -122,7 +148,7 @@ class QzoneH5API:
 
         :param attach_info: The ``attach_info`` field from last call.
             Pass an empty string equals to call :meth:`.index`.
-        :return: If success, the ``data`` field of the response.
+        :return: If success, the response.
         """
         if not self.qzone_tokens.get(self.login.uin) or not attach_info:
             return await self.index()
@@ -137,7 +163,7 @@ class QzoneH5API:
         :param hostuin: uin of the user
         :param attach_info: The ``attach_info`` field from last call.
             Pass an empty string equals to call :meth:`.index`.
-        :return: If success, the ``data`` field of the response.
+        :return: If success, the response.
         """
         if not self.qzone_tokens.get(hostuin) or not attach_info:
             return (await self.profile(hostuin)).feedpage
@@ -213,6 +239,7 @@ class QzoneH5API:
         :param content: comment content
         :param photos: photos to be attached, usually returned by :meth:`.preupload_photos`
         :param busi_param: optional encoded params from :obj:`FeedOperation.operation.busi_param`
+        :param feedsType: feed type
         :param abstime: required if `appid != 311`
         :param private: is private comment
 
@@ -265,6 +292,8 @@ class QzoneH5API:
         photos: t.Optional[t.Sequence[t.Union[PhotoData, PicInfo]]] = None,
         sync_weibo=False,
         ugc_right: UgcRight = UgcRight.all,
+        allow_uins: t.Optional[t.Sequence[int]] = None,
+        deny_uins: t.Optional[t.Sequence[int]] = None,
     ) -> PublishMoodResp:
         """Publish a feed.
 
@@ -272,12 +301,18 @@ class QzoneH5API:
         :param photos: photos to be attached, usually returned by :meth:`.preupload_photos`
         :param sync_weibo: sync to weibo, default to false
         :param ugc_right: access right, default to "Available to Everyone".
+        :param allow_uins: when ``ugc_right=part``, only these QQ users can see this feed.
+        :param deny_uins: when ``ugc_right=blacklist``, these QQ users cannot see this feed.
 
         .. seealso:: :meth:`.preupload_photos`, :meth:`.upload_pic`
         """
         photos = photos or []
+        kw = dict(locals())
+        kw.pop("self")
+        kw["allow_uins"] = kw.get("allow_uins") or []
+        kw["deny_uins"] = kw.get("deny_uins") or []
         return await self.call(
-            PublishMoodApi(params=PublishMoodParams.model_validate(locals(), from_attributes=True))
+            PublishMoodApi(params=PublishMoodParams.model_validate(kw, from_attributes=True))
         )
 
     async def upload_pic(
@@ -288,6 +323,11 @@ class QzoneH5API:
         quality: t.Union[int, float] = 70,
     ) -> UploadPicResponse:
         """
+        :param picture: image data or path
+        :param width: image width, if provided with height, the image will not be compressed
+        :param height: image height, if provided with width, the image will not be compressed
+        :param quality: compression quality, default to 70
+
         .. versionchanged:: 1.8.5
 
             In version <= 1.8.4, user is responsible for compressing a image and this api
@@ -324,6 +364,8 @@ class QzoneH5API:
         """Preupload photos before publishing a feed.
 
         :param upload_pics: List of :obj:`.UploadPicResponse`, usually returned by :meth:`.upload_pic`
+        :param cur_num: current photo number, default to 0
+        :param upload_hd: whether to upload HD version, default to False
 
         .. seealso:: :meth:`.upload_pic`
         """

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/src/aioqzone/api/login/__init__.py

@@ -42,6 +42,12 @@ class ConstLoginMan(Loginable):
         *,
         ch_login_notify: t.Optional[FutureStore] = None,
     ) -> None:
+        """Initialize with a pre-existing cookie dict.
+
+        :param uin: QQ number
+        :param cookie: pre-existing cookie dict
+        :param ch_login_notify: whether to enable login event emission
+        """
         super().__init__(uin, ch_login_notify=ch_login_notify)
         self.cookie = {} if cookie is None else cookie
 
@@ -63,17 +69,30 @@ class ConstLoginMan(Loginable):
 
 
 class UpLoginManager(Loginable):
+    """Login manager using uin-password authentication.
+
+    Wraps :class:`~qqqr.up.UpWebLogin` (or :class:`~qqqr.up.UpH5Login`)
+    and provides cookie refresh, captcha/SMS handling via hooks.
+    """
+
     def __init__(
         self,
         client: ClientAdapter,
         config: UpLoginConfig,
         *,
-        h5=True,
+        h5: bool = True,
         ch_login_notify: t.Optional[FutureStore] = None,
     ) -> None:
+        """Initialize UP (uin-password) login manager.
+
+        :param client: HTTP client
+        :param config: UP login config including uin and password
+        :param h5: use H5 endpoint (default True)
+        :param ch_login_notify: enable login event emission
+        """
         super().__init__(config.uin, ch_login_notify=ch_login_notify)
-        self.client = client
-        self.config = config
+        self.client = client  #: HTTP client
+        self.config = config  #: Login config instance
         self.h5(h5, clear_cookie=False)  # init uplogin
 
     @retry(
@@ -101,6 +120,7 @@ class UpLoginManager(Loginable):
                 raise TryAgain from e
             raise
         except NotImplementedError:
+            # intended: forwarded as NeedSmsVerify
             from qqqr.constant import StatusCode
 
             raise TencentLoginError(StatusCode.NeedSmsVerify, "需要手机验证")
@@ -108,7 +128,7 @@ class UpLoginManager(Loginable):
             log.warning(f"密码登录：{type(e).__name__}，重试", exc_info=True)
             log.debug(e.args, extra=e.__dict__)
             raise TryAgain from e
-        except BaseException as e:
+        except Exception as e:
             log.fatal("密码登录异常", exc_info=True)
             raise UnexpectedLoginError from e
 
@@ -142,17 +162,30 @@ class UpLoginManager(Loginable):
 
 
 class QrLoginManager(Loginable):
+    """Login manager using QR code authentication.
+
+    Wraps :class:`~qqqr.qr.QrLogin` and emits QR image via the
+    ``qr_fetched`` hook for downstream display.
+    """
+
     def __init__(
         self,
         client: ClientAdapter,
         config: QrLoginConfig,
         *,
-        h5=True,
+        h5: bool = True,
         ch_login_notify: t.Optional[FutureStore] = None,
     ) -> None:
+        """Initialize QR code login manager.
+
+        :param client: HTTP client
+        :param config: QR login config including uin
+        :param h5: use H5 endpoint (default True)
+        :param ch_login_notify: enable login event emission
+        """
         super().__init__(config.uin, ch_login_notify=ch_login_notify)
-        self.client = client
-        self.config = config
+        self.client = client  #: HTTP client
+        self.config = config  #: Login config instance
         self.h5(h5, clear_cookie=False)  # init uplogin
 
     async def _new_cookie(self) -> t.Dict[str, str]:
@@ -178,8 +211,8 @@ class QrLoginManager(Loginable):
         except (GeneratorExit, ClientError) as e:
             log.warning(f"二维码登录：{type(e).__name__}，重试", exc_info=True)
             log.debug(e.args, extra=e.__dict__)
-            raise TryAgain
-        except BaseException as e:
+            raise TryAgain from e
+        except Exception as e:
             log.fatal("二维码登录异常", exc_info=True)
             raise UnexpectedLoginError from e
 

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/src/aioqzone/api/login/_base.py

@@ -1,3 +1,10 @@
+"""Abstract login manager base.
+
+Defines :class:`Loginable` ABC — the interface all login managers
+implement. Provides cookie caching, gtk computation, and login event
+emission.
+"""
+
 import asyncio
 from abc import ABC, abstractmethod
 from time import time
@@ -10,7 +17,17 @@ from qqqr.utils.encrypt import gtk
 
 
 class Loginable(ABC):
-    """Abstract class represents a login manager."""
+    """Abstract login manager interface.
+
+    Subclasses implement :meth:`_new_cookie` to provide the actual login
+    flow (QR, UP, or static cookie). This base class handles cookie
+    caching, gtk computation, and login event emission.
+
+    .. seealso::
+        :class:`~aioqzone.api.login.ConstLoginMan`,
+        :class:`~aioqzone.api.login.UpLoginManager`,
+        :class:`~aioqzone.api.login.QrLoginManager`
+    """
 
     last_login: float = 0
     """Last login time stamp. 0 represents no login since created."""
@@ -21,13 +38,15 @@ class Loginable(ABC):
 
     def __init__(self, uin: int, ch_login_notify: Optional[FutureStore] = None) -> None:
         super().__init__()
-        self.uin = uin
+        self.uin = uin  #: Login QQ number
         self.cookie: Dict[str, str] = {}
-        self.lock = asyncio.Lock()
+        self.lock = asyncio.Lock()  #: Lock to serialize concurrent cookie refresh attempts
         self.ch_login_notify = ch_login_notify or FutureStore()
 
         self.login_success = MT.login_success()
+        """Emitted after a successful login."""
         self.login_failed = MT.login_failed()
+        """Emitted after a failed login attempt."""
 
     @abstractmethod
     async def _new_cookie(self) -> Dict[str, str]:
@@ -46,7 +65,7 @@ class Loginable(ABC):
         an actual login at the same time, other requests will block until the first is complete
         and share the cookie from this single login.
 
-        :return: cookie. Shouldn't be a cached one.
+        :return: True if login succeeded, False otherwise.
         """
         if self.lock.locked():
             last_gtk = self.gtk
@@ -57,7 +76,7 @@ class Loginable(ABC):
             async with self.lock:
                 try:
                     self.cookie = await self._new_cookie()
-                except BaseException as e:
+                except Exception as e:
                     self.ch_login_notify.add_awaitable(self.login_failed.emit(self.uin, e))
                     return False
                 else:

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/src/aioqzone/exception.py

@@ -1,3 +1,10 @@
+"""aioqzone exception hierarchy.
+
+Defines :class:`QzoneError` (HTTP OK but Qzone returned an error code),
+:class:`UnexpectedLoginError`, and :class:`CorruptError`.
+"""
+
+
 class QzoneError(RuntimeError):
     """HTTP OK, but Qzone returns an error code."""
 
@@ -8,7 +15,7 @@ class QzoneError(RuntimeError):
         self.robj = robj
         if len(args) > 0 and isinstance(args[0], str):
             self.msg = args[0]
-        super().__init__(self, *args)
+        super().__init__(*args)
 
     def __str__(self) -> str:
         return f"QzoneCode {self.code}: {self.msg}"

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/src/aioqzone/message.py

@@ -1,3 +1,9 @@
+"""tylisten hook definitions for aioqzone events.
+
+Defines :func:`login_success` and :func:`login_failed` hooks, and
+re-exports QR/UP/captcha hooks from :mod:`qqqr.message`.
+"""
+
 import typing as t
 
 from tylisten import hookdef

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/src/aioqzone/model/api/__init__.py

@@ -1,3 +1,11 @@
+"""Qzone API endpoint definitions.
+
+Each class in this module defines a Qzone H5 API endpoint — its URL,
+HTTP method, request params type, and response type. The :class:`QzoneApi`
+base class provides common infrastructure; concrete subclasses wire up
+specific endpoints.
+"""
+
 import typing as t
 
 from pydantic import BaseModel, Field
@@ -33,6 +41,8 @@ class QzoneApi(BaseModel, t.Generic[TyRequest, TyResponse]):
 
 
 class IndexPageApi(QzoneApi[QzoneRequestParams, IndexPageResp]):
+    """H5 Qzone landing page API. GET ``/mqzone/index``. Returns :class:`IndexPageResp` with qzonetoken."""
+
     response: t.ClassVar = IndexPageResp
     http_method: t.ClassVar[TyHttpMethod] = "GET"
     path: t.ClassVar[str] = "/mqzone/index"
@@ -41,6 +51,8 @@ class IndexPageApi(QzoneApi[QzoneRequestParams, IndexPageResp]):
 
 
 class UserProfileApi(QzoneApi[ProfileParams, ProfilePagePesp]):
+    """User profile page API. GET ``/mqzone/profile``. Returns :class:`ProfilePagePesp`."""
+
     response: t.ClassVar = ProfilePagePesp
     http_method: t.ClassVar[TyHttpMethod] = "GET"
     path: t.ClassVar[str] = "/mqzone/profile"
@@ -49,18 +61,24 @@ class UserProfileApi(QzoneApi[ProfileParams, ProfilePagePesp]):
 
 
 class FeedPageApi(QzoneApi[ActiveFeedsParams, FeedPageResp]):
+    """Active feeds pagination API. GET ``/mqzone_feeds/getActiveFeeds``. Returns :class:`FeedPageResp`."""
+
     response: t.ClassVar = FeedPageResp
     http_method: t.ClassVar[TyHttpMethod] = "GET"
     path: t.ClassVar[str] = "/webapp/json/mqzone_feeds/getActiveFeeds"
 
 
 class ShuoshuoApi(QzoneApi[ShuoshuoParams, DetailResp]):
+    """Feed detail (shuoshuo) API. GET ``/mqzone_detail/shuoshuo``. Returns :class:`DetailResp`."""
+
     response: t.ClassVar = DetailResp
     http_method: t.ClassVar[TyHttpMethod] = "GET"
     path: t.ClassVar[str] = "/webapp/json/mqzone_detail/shuoshuo"
 
 
 class GetFeedsApi(QzoneApi[GetFeedsParams, ProfileResp]):
+    """User feeds pagination API. GET ``/get_feeds``. Returns :class:`ProfileResp`."""
+
     response: t.ClassVar = ProfileResp
     http_method: t.ClassVar[TyHttpMethod] = "GET"
     host: t.ClassVar[str] = "https://mobile.qzone.qq.com"
@@ -68,6 +86,8 @@ class GetFeedsApi(QzoneApi[GetFeedsParams, ProfileResp]):
 
 
 class GetCountApi(QzoneApi[GetCountParams, FeedCount]):
+    """New feeds count / keep-alive API. GET ``/feeds/mfeeds_get_count``. Returns :class:`FeedCount`."""
+
     response: t.ClassVar = FeedCount
     params: GetCountParams = Field(default_factory=GetCountParams)
 
@@ -78,16 +98,22 @@ class GetCountApi(QzoneApi[GetCountParams, FeedCount]):
 
 
 class LikeApi(QzoneApi[DolikeParam, SingleReturnResp]):
+    """Like a feed. POST ``/cgi-bin/likes/internal_dolike_app``. Returns :class:`SingleReturnResp`."""
+
     response: t.ClassVar = SingleReturnResp
     http_method: t.ClassVar[TyHttpMethod] = "POST"
     path: t.ClassVar[str] = "/proxy/domain/w.qzone.qq.com/cgi-bin/likes/internal_dolike_app"
 
 
 class UnlikeApi(LikeApi):
+    """Unlike a feed. POST ``/cgi-bin/likes/internal_unlike_app``. Extends :class:`LikeApi`."""
+
     path: t.ClassVar[str] = "/proxy/domain/w.qzone.qq.com/cgi-bin/likes/internal_unlike_app"
 
 
 class AddCommentApi(QzoneApi[AddCommentParams, AddCommentResp]):
+    """Add comment (JSON API). POST ``/qzoneOperation/addComment``. Returns :class:`AddCommentResp`."""
+
     response: t.ClassVar = AddCommentResp
     http_method: t.ClassVar[TyHttpMethod] = "POST"
     path: t.ClassVar[str] = "/webapp/json/qzoneOperation/addComment"
@@ -95,24 +121,32 @@ class AddCommentApi(QzoneApi[AddCommentParams, AddCommentResp]):
 
 
 class AddCommentApiLegacy(QzoneApi[AddCommentParamsLegacy, AddCommentLegacyResp]):
+    """Add comment with photos (legacy API). POST ``/cgi-bin/emotion_cgi_re_feeds``. Returns :class:`AddCommentLegacyResp`."""
+
     response: t.ClassVar = AddCommentLegacyResp
     http_method: t.ClassVar[TyHttpMethod] = "POST"
     path: t.ClassVar[str] = "/proxy/domain/taotao.qzone.qq.com/cgi-bin/emotion_cgi_re_feeds"
 
 
 class DeleteCommentApi(QzoneApi[DeleteCommentParams, DeleteCommentResp]):
+    """Delete a comment. POST ``/cgi-bin/emotion_cgi_delcomment_ugc``. Returns :class:`DeleteCommentResp`."""
+
     response: t.ClassVar = DeleteCommentResp
     http_method: t.ClassVar[TyHttpMethod] = "POST"
     path: t.ClassVar[str] = "/proxy/domain/taotao.qzone.qq.com/cgi-bin/emotion_cgi_delcomment_ugc"
 
 
 class ListFriendApi(QzoneApi):
+    """List friends (reserved, not yet wired). GET ``/friend/mfriend_list``."""
+
     http_method: t.ClassVar[TyHttpMethod] = "GET"
     host: t.ClassVar[str] = "https://mobile.qzone.qq.com"
     path: t.ClassVar[str] = "/friend/mfriend_list"
 
 
 class PublishMoodApi(QzoneApi[PublishMoodParams, PublishMoodResp]):
+    """Publish a mood feed. POST ``/mood/publish_mood``. Returns :class:`PublishMoodResp`."""
+
     response: t.ClassVar = PublishMoodResp
     http_method: t.ClassVar[TyHttpMethod] = "POST"
     host: t.ClassVar[str] = "https://mobile.qzone.qq.com"
@@ -120,6 +154,8 @@ class PublishMoodApi(QzoneApi[PublishMoodParams, PublishMoodResp]):
 
 
 class AddOperationApi(QzoneApi):
+    """Generic operation API. POST ``/operation/operation_add``."""
+
     response: t.Type[QzoneResponse]
     http_method: t.ClassVar[TyHttpMethod] = "POST"
     host: t.ClassVar[str] = "https://mobile.qzone.qq.com"
@@ -127,6 +163,8 @@ class AddOperationApi(QzoneApi):
 
 
 class UploadPicApi(QzoneApi[UploadPicParams, UploadPicResponse]):
+    """Upload image. POST ``/cgi-bin/upload/cgi_upload_pic_v2``. Returns :class:`UploadPicResponse`."""
+
     response: t.ClassVar = UploadPicResponse
     http_method: t.ClassVar[TyHttpMethod] = "POST"
     host: t.ClassVar[str] = "https://mobile.qzone.qq.com"
@@ -134,6 +172,8 @@ class UploadPicApi(QzoneApi[UploadPicParams, UploadPicResponse]):
 
 
 class PhotosPreuploadApi(QzoneApi[PhotosPreuploadParams, PhotosPreuploadResponse]):
+    """Preupload photos before publishing. POST ``/cgi-bin/upload/cgi_upload_pic_v2``. Returns :class:`PhotosPreuploadResponse`."""
+
     response: t.ClassVar = PhotosPreuploadResponse
     http_method: t.ClassVar[TyHttpMethod] = "POST"
     host: t.ClassVar[str] = "https://mobile.qzone.qq.com"
@@ -141,6 +181,8 @@ class PhotosPreuploadApi(QzoneApi[PhotosPreuploadParams, PhotosPreuploadResponse
 
 
 class AvatarApi(QzoneApi[AvatarParams, AvatarResponse]):
+    """Get avatar by uin (no login required). GET ``/qzone/{hostuin}/{hostuin}/{size}``. Returns :class:`AvatarResponse`."""
+
     response: t.ClassVar = AvatarResponse
     login_required: t.ClassVar[bool] = False
     http_method: t.ClassVar[TyHttpMethod] = "GET"
@@ -149,6 +191,8 @@ class AvatarApi(QzoneApi[AvatarParams, AvatarResponse]):
 
 
 class SetTopApi(QzoneApi[SetTopParams, SingleReturnResp]):
+    """Set/unset feed as top. POST ``/cgi-bin/feeds/cgi_settopfeed``. Returns :class:`SingleReturnResp`."""
+
     response: t.ClassVar = SingleReturnResp
     http_method: t.ClassVar[TyHttpMethod] = "POST"
     host: t.ClassVar[str] = "user.qzone.qq.com"

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/src/aioqzone/model/api/feed.py

@@ -1,3 +1,10 @@
+"""Feed data models.
+
+Defines the core feed data structures including :class:`FeedData`,
+:class:`FeedCommon`, :class:`UserInfo`, feed media types, and related
+enums. These models represent the Qzone feed JSON structure.
+"""
+
 import typing as t
 from enum import IntEnum
 

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/src/aioqzone/model/api/request.py

@@ -1,3 +1,10 @@
+"""Qzone API request parameter models.
+
+Defines :class:`QzoneRequestParams` and its subclasses for each API
+endpoint. Each subclass carries fields specific to that endpoint and
+provides :meth:`build_params` for serialization.
+"""
+
 import typing as t
 from base64 import b64encode
 from io import BytesIO
@@ -190,6 +197,11 @@ class PublishMoodParams(QzoneRequestParams):
     )
     ugc_right: UgcRight = UgcRight.all
 
+    allow_uins: t.List[int] = Field(default_factory=list)
+    """When ugc_right=part (16), only these QQ users can see this shuoshuo."""
+    deny_uins: t.List[int] = Field(default_factory=list)
+    """When ugc_right=blacklist (128), these QQ users cannot see this shuoshuo."""
+
     opr_type: str = "publish_shuoshuo"
     format: str = "json"
     # lat: int
@@ -200,6 +212,10 @@ class PublishMoodParams(QzoneRequestParams):
     def richval(self, photos: t.List[PhotoData]):
         return " ".join(i.to_richval() for i in photos)
 
+    @field_serializer("allow_uins", "deny_uins")
+    def uinlist_to_str(self, uins: t.List[int]) -> str:
+        return ",".join(str(u) for u in uins) if uins else ""
+
 
 class DeleteUgcParams(QzoneRequestParams):
     uin_fields = ("res_uin",)

{aioqzone-1.9.6.dev6 → aioqzone-1.9.8.dev1}/src/aioqzone/model/api/response.py

@@ -1,3 +1,10 @@
+"""Qzone API response models.
+
+Defines :class:`QzoneResponse` base class and its subclasses for each
+API endpoint. Includes factory methods :meth:`~QzoneResponse.from_response_object`
+and :meth:`~QzoneResponse.response_to_object` for HTTP response parsing.
+"""
+
 import re
 import typing as t
 from contextlib import suppress
@@ -212,7 +219,8 @@ class ProfilePagePesp(QzoneResponse):
         data = script[m.end() - 1 : m.end() + entire_closing(script[m.end() - 1 :], "[")]
         data = re.sub(r",,\]$", "]", data)
         data = json_loads(data)
-        assert isinstance(data, list)
+        if not isinstance(data, list):
+            raise TryAgain("ProfilePageResponse: profile not returned")
         if len(data) < 2:
             raise TryAgain("ProfilePageResponse: profile not returned")
 
@@ -261,7 +269,8 @@ class AddCommentLegacyResp(QzoneResponse):
             raise TryAgain("AddCommentLegacyResponse: script tag not found")
 
         m = response_callback.search(script)
-        assert m
+        if not m:
+            raise TryAgain("AddCommentLegacyResponse: callback not found")
         return validate_strdict(json_loads(m.group(1)))
 
 
@@ -280,7 +289,8 @@ class DeleteCommentResp(QzoneResponse):
             raise TryAgain("DeleteCommentResponse: script tag not found")
 
         m = response_callback.search(script)
-        assert m
+        if not m:
+            raise TryAgain("DeleteCommentResponse: callback not found")
         return validate_strdict(json_loads(m.group(1)))
 
 
@@ -306,7 +316,8 @@ class UploadPicResponse(QzoneResponse):
     @classmethod
     async def response_to_object(cls, response: ClientResponse) -> StrDict:
         m = response_callback.search(await response.text())
-        assert m
+        if not m:
+            raise TryAgain("UploadPicResponse: callback not found")
         return validate_strdict(json_loads(m.group(1)))
 
 
@@ -331,10 +342,12 @@ class PhotosPreuploadResponse(QzoneResponse):
     @classmethod
     async def response_to_object(cls, response: ClientResponse) -> StrDict:
         m = response_callback.search(await response.text())
-        assert m
+        if not m:
+            raise TryAgain("PhotosPreuploadResponse: callback not found")
 
         picinfos = json_loads(m.group(1))
-        assert isinstance(picinfos, list)
+        if not isinstance(picinfos, list):
+            raise TryAgain("PhotosPreuploadResponse: picinfos not a list")
         return dict(photos=[PicInfo.from_response_object(info["picinfo"]) for info in picinfos])  # type: ignore