aioqzone 1.8.2.dev3__tar.gz → 1.8.3.dev1__tar.gz

{aioqzone-1.8.2.dev3 → aioqzone-1.8.3.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: aioqzone
-Version: 1.8.2.dev3
+Version: 1.8.3.dev1
 Summary: A Python wrapper for Qzone login and H5 APIs.
 Home-page: https://github.com/aioqzone/aioqzone
 License: AGPL-3.0

{aioqzone-1.8.2.dev3 → aioqzone-1.8.3.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "aioqzone"
-version = "1.8.2.dev3"
+version = "1.8.3.dev1"
 description = "A Python wrapper for Qzone login and H5 APIs."
 authors = ["aioqzone <zzzzss990315@gmail.com>"]
 license = "AGPL-3.0"

{aioqzone-1.8.2.dev3 → aioqzone-1.8.3.dev1}/src/aioqzone/model/protocol/config.py

@@ -26,3 +26,5 @@ class QrLoginConfig(LoginConfig):
     """Maximum QR code refresh times."""
     poll_freq: float = 3
     """QR status polling interval."""
+    no_push: bool = False
+    """Do not try to push the QR code to user's client."""

aioqzone-1.8.3.dev1/src/qqqr/__init__.py

@@ -0,0 +1,4 @@
+"""
+QQQR is an API-level simulation of Qzone web login process. Currently this package
+includes QR login and password login. A captcha verifier is also contained to pass TDC.
+"""

{aioqzone-1.8.2.dev3 → aioqzone-1.8.3.dev1}/src/qqqr/qr/__init__.py

@@ -28,13 +28,17 @@ PTLOGIN2 = URL("https://ptlogin2.qq.com")
 
 @dataclass(unsafe_hash=True)
 class QR:
+    """Class :class:`QR` represents a QR code."""
+
     png: t.Optional[bytes]
-    """If None, the QR is pushed to user's client."""
+    """QR code content. If None, the QR is pushed to user's client."""
     sig: str
     expired: bool = False
+    """Whether the QR code is expired."""
 
     @property
     def pushed(self):
+        """Whether the QR code is pushed to user's client."""
         return self.png is None
 
 
@@ -49,9 +53,12 @@ class QrSession(LoginSession):
     ) -> None:
         super().__init__(login_sig=login_sig, create_time=create_time)
         self.refreshed = refresh_times
+        """QR code refresh times counter."""
         self.current_qr = first_qr
+        """A :class:`QrSession` keeps a :class:`QR` object as current QR code."""
 
     def new_qr(self, qr: QR):
+        """Add a new QR code to this session."""
         self.current_qr.expired = True
         self.current_qr = qr
         self.refreshed += 1
@@ -61,14 +68,36 @@ class _QrHookMixin:
     def __init__(self, *args, **kwds) -> None:
         super().__init__(*args, **kwds)
         self.qr_fetched = MT.qr_fetched.with_timeout(60)
+        """This emitter is triggered when a QR code is fetched."""
         self.qr_cancelled = MT.qr_cancelled()
+        """This emitter is triggered when QR login is cancelled."""
         self.cancel = asyncio.Event()
+        """Async-event indicating whether the loop should cancel the QR login."""
         self.refresh = asyncio.Event()
+        """Async-event indicating whether the loop should refresh the QR code immediately."""
 
 
 class QrLogin(LoginBase[QrSession], _QrHookMixin):
-    async def new(self) -> QrSession:
+    async def new(self, no_push=False) -> QrSession:
+        """Create a :class:`QrSession`. This method will:
+
+        1. GET ``xlogin`` url to get ``pt_login_sig`` cookie;
+
+        #. Try "quick login" (the QR code is pushed to user's client);
+
+        #. Whether the QR code is pushed or not, a :class:`QR` object is created
+           and is hold by the returned :class:`QrSession`.
+
+        :param no_push: Do not try to push the QR code to user's client.
+        :return: a :class:`QrSession`
+
+        .. versionchanged:: 1.8.3
+
+            Added :obj:`no_push` param.
+        """
         login_sig = await self._pt_login_sig()
+        if no_push:
+            return QrSession(await self.show(), login_sig=login_sig)
 
         cookie = self.client.cookie_jar.filter_cookies(PTLOGIN2).get("pt_guid_sig")
         push_qr = False
@@ -88,9 +117,10 @@ class QrLogin(LoginBase[QrSession], _QrHookMixin):
         return QrSession(await self.show(push_qr), login_sig=login_sig)
 
     async def show(self, push_qr=False) -> QR:
-        """``ptqrshow`` api.
+        """This method will call ``ptqrshow`` api and wrap the response QR bytes into :class:`QR`.
 
         :param push_qr: push QR to mobile client.
+        :return: a :class:`QR` object.
         """
         data = {
             "appid": self.app.appid,
@@ -170,26 +200,37 @@ class QrLogin(LoginBase[QrSession], _QrHookMixin):
         *,
         refresh_times: int = 6,
         poll_freq: float = 3,
+        no_push=False,
     ):
-        """Loop until cookie is returned or max `refresh_times` exceeds.
+        """Loop until cookie is returned or max :obj:`refresh_times` exceeds.
+
         - This method will emit :obj:`.qr_fetched` event if a new qrcode is fetched.
-        - If qr is not scanned after `refresh_times`, it will raise :exc:`UserTimeout`.
+
+        - If the QR code is not scanned after :obj:`refresh_times`,
+          it will raise :exc:`~qqqr.exception.UserTimeout`.
+
         - If :obj:`.refresh` is set, it will refresh qrcode at once without increasing expire counter.
-        - If :obj:`.cancel` is set, it will raise :exc:`UserBreak` before next polling.
+
+        - If :obj:`.cancel` is set, it will raise :exc:`~qqqr.exception.UserBreak` before next polling.
 
         :meta public:
         :param refresh_times: max qr expire times.
         :param poll_freq: interval between two status polling, in seconds, default as 3.
+        :param no_push: Do not try to push the QR code to user's client.
 
-        :raise `UserTimeout`: if qr is not scanned after `refresh_times` expires.
+        :raise `UserTimeout`: if the QR code is not scanned after :obj:`refresh_times` expires.
         :raise `UserBreak`: if :obj:`.cancel` is set.
+
+        .. versionchanged:: 1.8.3
+
+            Added :obj:`no_push` param.
         """
         self.refresh.clear()
         self.cancel.clear()
 
         cnt_expire = 0
         renew = False
-        sess = await self.new()
+        sess = await self.new(no_push)
 
         while cnt_expire < refresh_times:
             # BUG: should we wrap hook errors here?
@@ -206,6 +247,7 @@ class QrLogin(LoginBase[QrSession], _QrHookMixin):
                 await asyncio.sleep(poll_freq)
                 stat = await self.poll(sess)
                 if stat.code == StatusCode.Expired:
+                    sess.current_qr.expired = True
                     cnt_expire += 1
                     break
                 elif stat.code == StatusCode.Authenticated:

{aioqzone-1.8.2.dev3 → aioqzone-1.8.3.dev1}/src/qqqr/up/web.py

@@ -99,6 +99,7 @@ class _UpHookMixin:
     def __init__(self, *args, **kwds) -> None:
         super().__init__(*args, **kwds)
         self.sms_code_input = MT.sms_code_input.with_timeout(60)
+        """This emitter is triggered when SMS verify code is needed during login."""
 
 
 class UpWebLogin(LoginBase[UpWebSession], _UpHookMixin):
@@ -132,9 +133,8 @@ class UpWebLogin(LoginBase[UpWebSession], _UpHookMixin):
             self.client, self.app.appid, str(self.login_page_url), fake_ip=fake_ip
         )
 
-    async def new(self):
-        """Create a :class:`UpWebSession`. This will call `check` api of Qzone, and receive result
-        about whether this login needs a captcha, sms verification, etc.
+    async def new(self) -> UpWebSession:
+        """Create a :class:`UpWebSession`. This will trigger a GET to ``xlogin`` url.
 
         :raise `aiohttp.ClientResponseError`: if response status != 200
 
@@ -143,6 +143,11 @@ class UpWebLogin(LoginBase[UpWebSession], _UpHookMixin):
         return UpWebSession(await self._pt_login_sig())
 
     async def check(self, sess: UpWebSession):
+        """This will call ``check`` api of Qzone, and receive result about
+        whether this login needs a captcha, sms verification, etc.
+
+        :param sess: Session got from :meth:`~UpWebLogin.new`.
+        """
         data = {
             "regmaster": "",
             "pt_tea": 2,
@@ -217,7 +222,7 @@ class UpWebLogin(LoginBase[UpWebSession], _UpHookMixin):
         data.update(const)
         return data
 
-    async def try_login(self, sess: UpWebSession):
+    async def try_login(self, sess: UpWebSession) -> LoginResp:
         """
         Check if current session meets the login condition.
         It takes a session object and returns response of this try.

aioqzone-1.8.2.dev3/src/qqqr/__init__.py

@@ -1,4 +0,0 @@
-"""
-QQQR is a simulation of Qzone web login process. Including QR login and password login.
-A captcha verifier is also contained to pass TDC.
-"""