aioqzone 1.9.7.dev1__tar.gz → 1.9.8.dev1__tar.gz

{aioqzone-1.9.7.dev1 → aioqzone-1.9.8.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aioqzone
-Version: 1.9.7.dev1
+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.7.dev1 → aioqzone-1.9.8.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aioqzone"
-version = "1.9.7.dev1"
+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.7.dev1 → 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.7.dev1 → 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 = {}
@@ -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.7.dev1 → 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(
@@ -143,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]:

{aioqzone-1.9.7.dev1 → 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

{aioqzone-1.9.7.dev1 → 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."""
 

{aioqzone-1.9.7.dev1 → 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.7.dev1 → 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.7.dev1 → 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.7.dev1 → 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.7.dev1 → 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

{aioqzone-1.9.7.dev1 → aioqzone-1.9.8.dev1}/src/aioqzone/model/protocol/__init__.py

@@ -8,7 +8,9 @@ from .config import *
 from .entity import *
 
 
-class PersudoCurkey(str):
+class PseudoCurkey(str):
+    """Pseudo curkey string helper."""
+
     def __new__(cls, uin: int, abstime: int):
         return str.__new__(cls, cls.build(uin, abstime))
 
@@ -31,6 +33,8 @@ class PersudoCurkey(str):
 
 
 class AlbumData(BaseModel):
+    """Album data model."""
+
     topicid: str
     pickey: str
     hostuin: int
@@ -38,6 +42,8 @@ class AlbumData(BaseModel):
 
 # LikeData is not a response of any API. It's just a type def.
 class LikeData(BaseModel):
+    """Like data model with helper methods for key construction."""
+
     unikey: str
     curkey: str
     appid: int
@@ -46,11 +52,11 @@ class LikeData(BaseModel):
     abstime: int
 
     @staticmethod
-    def persudo_curkey(uin: int, abstime: int):
-        return str(PersudoCurkey(uin, abstime))
+    def pseudo_curkey(uin: int, abstime: int):
+        return str(PseudoCurkey(uin, abstime))
 
     @staticmethod
-    def persudo_unikey(appid: int, uin: int, fid: str):
+    def pseudo_unikey(appid: int, uin: int, fid: str):
         if appid == 311:
             return f"https://user.qzone.qq.com/{uin}/mood/{fid}"
 

{aioqzone-1.9.7.dev1 → aioqzone-1.9.8.dev1}/src/aioqzone/model/protocol/config.py

@@ -1,3 +1,10 @@
+"""Login configuration models.
+
+Defines :class:`LoginConfig`, :class:`UpLoginConfig`, and
+:class:`QrLoginConfig` — pydantic :class:`BaseSettings` models for
+login parameters.
+"""
+
 import typing as t
 from ipaddress import IPv4Address
 

{aioqzone-1.9.7.dev1 → aioqzone-1.9.8.dev1}/src/aioqzone/model/protocol/entity.py

@@ -10,6 +10,8 @@ from pydantic import BaseModel, Field, HttpUrl
 
 
 class HasContent(BaseModel):
+    """Mixin for models that contain content text."""
+
     content: str = ""
 
 
@@ -67,4 +69,6 @@ class LinkEntity(ConEntity):
 
 
 class HasConEntity(HasContent):
+    """Mixin for models that contain content entities."""
+
     entities: Optional[List[ConEntity]] = Field(default=None, alias="conlist")

{aioqzone-1.9.7.dev1 → aioqzone-1.9.8.dev1}/src/aioqzone/utils/entity.py

@@ -1,3 +1,9 @@
+"""Content entity parsing utilities.
+
+Provides :func:`finfo_box_entities` and :func:`split_entities` for
+extracting structured entities from feed content HTML.
+"""
+
 import re
 from typing import List
 
@@ -38,6 +44,12 @@ RE_ENTITY = re.compile(entity_rules, re.VERBOSE)
 
 
 def finfo_box_entities(finfo: HtmlElement) -> List[ConEntity]:
+    """Extract entities from a feed info box HTML element.
+
+    :param finfo: parsed HTML element of the feed info box
+    :returns: list of entity dicts
+    """
+
     def yield_children(elm: HtmlElement):
         if elm.text is not None:
             yield elm.text
@@ -72,6 +84,11 @@ def finfo_box_entities(finfo: HtmlElement) -> List[ConEntity]:
 
 
 def split_entities(s: str) -> List[ConEntity]:
+    """Split a content string into text and entity segments.
+
+    :param s: raw content string with entity markup
+    :returns: list of text/entity segment dicts
+    """
     entities: List[ConEntity] = []
     pos = 0
     for m in RE_ENTITY.finditer(s):