itd-sdk 2.1.2__tar.gz → 2.3.0__tar.gz

{itd_sdk-2.1.2 → itd_sdk-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: itd-sdk
-Version: 2.1.2
+Version: 2.3.0
 Summary: ITD client for python
 Keywords: itd,itdsocial
 Author: firedotguy
@@ -11,7 +11,6 @@ Classifier: Natural Language :: Russian
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Framework :: Pydantic :: 2
-Classifier: License :: OSI Approved :: MIT License
 Requires-Dist: requests~=2.32.5
 Requires-Dist: pydantic>=2.12.5,<2.14.0
 Requires-Dist: sseclient-py~=1.9.0

itd_sdk-2.3.0/itd/api/auth.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from requests import Response
+
+from itd.base import catch_errors, rate_limit
+from itd.enums import AuthLevel
+from itd.exceptions import (
+    InvalidPasswordError, SamePasswordError, InvalidOldPasswordError, SessionNotFoundError,
+    SessionExpiredError, SessionRevokedError, InvalidCredentials, CaptchaFailedError,
+    EmailDomainNotAllowed
+)
+if TYPE_CHECKING:
+    from itd.client import Client
+
+@rate_limit()
+@catch_errors(SessionExpiredError(), SessionNotFoundError(), SessionRevokedError())
+def refresh_token(client: Client) -> Response:
+    return client.request('post', 'v1/auth/refresh', level=AuthLevel.REFRESH)
+
+@rate_limit()
+@catch_errors(InvalidPasswordError(), SamePasswordError(), InvalidOldPasswordError())
+def change_password(client: Client, old: str, new: str) -> Response:
+    return client.request('post', 'v1/auth/change-password', {'newPassword': new, 'oldPassword': old})
+
+@rate_limit()
+@catch_errors()
+def logout(client: Client) -> Response:
+    return client.request('post', 'v1/auth/logout', level=AuthLevel.REFRESH)
+
+
+@rate_limit()
+@catch_errors(InvalidCredentials(), CaptchaFailedError(), EmailDomainNotAllowed())
+def sign_in(client: Client, email: str, password: str, turnstile: str):
+    return client.request('post', 'v1/auth/sign-in', {'email': email, 'password': password, 'turnstileToken': turnstile}, level=AuthLevel.NO)

itd_sdk-2.3.0/itd/api/dwell.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from itd.base import catch_errors, rate_limit
+if TYPE_CHECKING:
+    from itd.client import Client
+
+
+@rate_limit()
+@catch_errors()
+def send_views(client: Client, objects: list[dict], sid: UUID):
+    return client.request('post', 'v1/i', {'e': objects, 'sid': str(sid)})
+
+
+@rate_limit()
+@catch_errors()
+def send_interactions(client: Client, objects: list[dict], sid: UUID):
+    return client.request('post', 'v1/x', {'e': objects, 'sid': str(sid)})

{itd_sdk-2.1.2 → itd_sdk-2.3.0}/itd/api/hashtags.py

@@ -4,15 +4,16 @@ from typing import TYPE_CHECKING
 
 from itd.exceptions import TooLargeError, NotFoundError
 from itd.base import catch_errors, rate_limit
+from itd.enums import AuthLevel
 if TYPE_CHECKING:
     from itd.client import Client
 
 @rate_limit()
 @catch_errors()
 def get_hashtags(client: Client, limit: int = 10):
-    return client.request('get', 'hashtags/trending', {'limit': limit})
+    return client.request('get', 'hashtags/trending', {'limit': limit}, level=AuthLevel.NO)
 
 @rate_limit()
 @catch_errors(TooLargeError('Hashtag'), NotFoundError('Hashtag', json_check=lambda json: json.get('data', {}).get('hashtag', '') is None))
 def get_posts_by_hashtag(client: Client, hashtag: str, cursor: UUID | None = None, limit: int = 20):
-    return client.request('get', f'hashtags/{hashtag}/posts', {'limit': limit, 'cursor': cursor})
+    return client.request('get', f'hashtags/{hashtag}/posts', {'limit': limit, 'cursor': cursor}, level=AuthLevel.NO)

{itd_sdk-2.1.2 → itd_sdk-2.3.0}/itd/api/search.py

@@ -4,9 +4,10 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from itd.client import Client
 from itd.exceptions import ValidationError
+from itd.enums import AuthLevel
 from itd.base import catch_errors, rate_limit
 
 @rate_limit(None, 0.5, 3)
 @catch_errors(ValidationError())
 def search(client: Client, query: str, user_limit: int = 5, hashtag_limit: int = 5):
-    return client.request('get', 'search', {'userLimit': user_limit, 'hashtagLimit': hashtag_limit, 'q': query})
+    return client.request('get', 'search', {'userLimit': user_limit, 'hashtagLimit': hashtag_limit, 'q': query}, level=AuthLevel.NO)

{itd_sdk-2.1.2 → itd_sdk-2.3.0}/itd/base.py

@@ -53,6 +53,9 @@ class ITDBaseModel:
             value._client = client
         object.__setattr__(self, name, value)
 
+    def _post_refresh(self):
+        pass
+
     @property
     def client(self) -> Client:
         return self._client
@@ -147,7 +150,6 @@ class ITDList[T](ITDBaseModel, list[T]):
             length = len(objects)
             if objects and (client or self.client).config.userposts_add_pinned_post and length == batch + 1: # skip pinned post
                 length -= 1
-            l.debug('%s', objects)
 
             if left is not None:
                 left -= length
@@ -265,6 +267,7 @@ def refresh_wrapper(func):
 
         # self._loading = False
         self._loaded = True
+        self._post_refresh()
 
     return wrapper
 
@@ -293,6 +296,8 @@ def catch_errors(*exceptions: ITDException):
 
             assert isinstance(res, Response)
             if res.status_code == 204:
+                if client.config.debug_response != DebugResponseMode.NO:
+                    l.debug('no response')
                 return res
 
             if client.config.debug_response == DebugResponseMode.BEFORE:
@@ -370,15 +375,15 @@ def rate_limit(delay_min: float | None = None, delay_mid: float | None = None, d
                 sleep(max(delay, 0))
             client.last_actions[func.__name__] = datetime.now()
 
-            if not client.config.retry_on_rate_limits:
+            if not client.config.retry_enabled:
                 return func(client, *args, **kwargs)
 
             while True:
                 try:
                     return func(client, *args, **kwargs)
-                except (RateLimitError, InternalError) as e:
-                    retry_after = getattr(e, 'retry_after', client.config.rate_limit_wait) or client.config.rate_limit_wait
-                    l.info('rate limit on %s; wait %ss', func.__name__, retry_after)
+                except (client.config._retry_exceptions) as e:
+                    retry_after = getattr(e, 'retry_after', client.config.rate_limit_wait) or client.config.retry_delay
+                    l.info('%s on %s: wait %ss', e.__class__.__name__, func.__name__, retry_after)
                     sleep(retry_after)
 
         return wrapper

{itd_sdk-2.1.2 → itd_sdk-2.3.0}/itd/client.py

@@ -6,13 +6,15 @@ from dataclasses import dataclass, field
 from requests import Session
 from requests.utils import default_user_agent
 from requests.adapters import HTTPAdapter
+from requests.exceptions import RequestException
 
 from itd._default import _default_client, set_default_client
-from itd.exceptions import UnauthorizedError, InsufficientAuthLevelError, AccessTokenExpiredError
+from itd.exceptions import UnauthorizedError, InsufficientAuthLevelError, AccessTokenExpiredError, RateLimitError, InternalError
 from itd.hashtag import Hashtag
 from itd.request import fetch, decode_jwt_payload
-from itd.enums import RateLimitMode, All, DebugResponseMode, ParseMode, Batch, BATCH, UserAgent
+from itd.enums import RateLimitMode, All, DebugResponseMode, ParseMode, Batch, BATCH, UserAgent, AuthLevel
 from itd.user import Me, User
+from itd.post import DwellTracker
 from itd.api.auth import refresh_token, change_password, logout
 from itd.api.search import search
 from itd.api.users import get_follow_status
@@ -28,25 +30,46 @@ class Config:
     rate_limit: RateLimitMode = RateLimitMode.MID
     rate_limit_default: int | None = None # overrides ratelimit mode  # rate limit for standard actions
     rate_limit_actions: dict[str, float | int] = field(default_factory=lambda: {}) # overrides ratelimit mode  # custom rate limits for specific actions (eg. {'add_comment': 10})
+
     # is_logging_enabled: bool = True # TODO
     # logging_level = 'DEBUG'
+
     is_default: bool = False
+
     userposts_add_pinned_post: bool = True
+
     auto_load: bool = True
     load_on_getitem: int | All | Batch | None = 1
     load_on_iter: int | All | Batch | None = BATCH
     force_load_lists: bool = False # load lists even if has_more is False
+
     debug_response: DebugResponseMode = DebugResponseMode.NO
+
     timeout: float = 30
     timeout_file: float = 120
+
     url: str = 'xn--d1ah4a.com'
     url_api: str | None = None
     user_agent: UserAgent | str = UserAgent.BROWSER
     solve_challenge: bool = True
+
     load_comments_from_post: bool = False
+
     parse_mode: ParseMode = ParseMode.NO
-    rate_limit_wait: int = 10 # delay before next attempt (after rate limit error) if retry_after is not provided
-    retry_on_rate_limits: bool = True
+
+    rate_limit_wait: int | None = None # DEPRECATED
+    retry_on_rate_limits: bool | None = None # DEPRECATED
+    retry_enabled: bool = True
+    retry_delay: float = 10 # delay before next attempt (after rate limit error) if retry_after is not provided in request
+    retry_max_retries: int | None = None # none for no limit
+    retry_exceptions: tuple[type[Exception]] | list[type[Exception]] | None = None
+
+    bypass_auth_level: bool = False
+
+    dwell_enabled: bool = True
+    dwell_max_buffer: int = 20
+    dwell_send_interval: float = 2
+    dwell_save_on_quit: bool = True
 
     def __post_init__(self):
         if self.rate_limit_default:
@@ -73,10 +96,19 @@ class Config:
             case _:
                 self._user_agent = self.user_agent
 
+        if self.rate_limit_wait is not None:
+            l.warning('config.rate_limit_wait is deprecated and will be removed in 2.4.0. Please use config.retry_delay')
+            self.retry_delay = self.rate_limit_wait
+        if self.retry_on_rate_limits is not None:
+            l.warning('config.retry_on_rate_limits is deprecated and will be removed in 2.4.0. Please use config.retry_enabled')
+            self.retry_enabled = self.retry_on_rate_limits
+
+        self._retry_exceptions = (tuple(self.retry_exceptions) if isinstance(self.retry_exceptions, list) else self.retry_exceptions) or (RateLimitError, InternalError, RequestException)
 
 
 
 class Client:
+    auth_level: AuthLevel = AuthLevel.NO
     access_token: str | None = None
     refresh_token: str | None = None
     _user = None
@@ -92,18 +124,26 @@ class Client:
         self.session.mount('https://', adapter)
 
         if access:
+            self.auth_level = AuthLevel.ACCESS
             self.access_token = access.replace('Bearer ', '')
 
         if refresh:
+            self.auth_level = AuthLevel.REFRESH
             self.refresh_token = refresh
             self.session.cookies.set('refresh_token', refresh, path='/', domain=self.config.url)
-            if access is None:
-                self.refresh_auth()
+            # if access is None:
+            #     self.refresh_auth()
 
         if _default_client is None or config.is_default:
             set_default_client(self)
 
-    def request(self, method: str, url: str, params: dict = {}, files: dict[str, tuple[str, BufferedReader | bytes]] = {}):
+        if self.auth_level > AuthLevel.NO and self.config.dwell_enabled:
+            self.dwell_tracker = DwellTracker(self)
+            self.dwell_tracker._start_timer()
+        else:
+            self.dwell_tracker = None
+
+    def request(self, method: str, url: str, params: dict = {}, files: dict[str, tuple[str, BufferedReader | bytes]] = {}, level=AuthLevel.ACCESS):
         """Сделать запрос
 
         Args:
@@ -112,11 +152,18 @@ class Client:
             params (dict, optional): Параметры. Defaults to {}.
             files (dict[str, tuple[str, BufferedReader | bytes]], optional): Файлы. Defaults to {}.
         """
-        l.debug('%s %s params=%s', method.upper(), url, params)
+        l.debug('%s %s params=%s authlevel=%s', method.upper(), url, params, level.value)
+
+        if level > self.auth_level and not self.config.bypass_auth_level:
+            raise InsufficientAuthLevelError(self.auth_level, level)
+
+        if level >= AuthLevel.ACCESS and self.access_token is None and url != 'v1/auth/refresh':
+            self.refresh_auth()
+
         def _fetch():
             return fetch(self, method, url, params, files)
 
-        if not self.refresh_token:
+        if not self.refresh_token or url == 'v1/auth/refresh':
             return _fetch()
 
         try:
@@ -132,8 +179,6 @@ class Client:
             str: Токен
         """
         l.debug('refresh token')
-        if not self.refresh_token:
-            raise InsufficientAuthLevelError()
 
         res = refresh_token(self)
         res.raise_for_status()

{itd_sdk-2.1.2 → itd_sdk-2.3.0}/itd/comment.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
 from uuid import UUID
 from datetime import datetime
 from math import ceil
@@ -5,13 +7,14 @@ from math import ceil
 from pydantic import Field, BaseModel, field_validator
 
 from itd.base import ITDBaseModel, ITDList
-from itd.client import Client
 from itd.enums import CommentSorting, ReportTargetType, ReportReason
 from itd.report import Report
 from itd.utils import parse_datetime, to_nullable_uuid, format_attachments, ATTACHMENTS
 from itd.api.comments import get_comments, add_comment, add_reply_comment, get_replies, like_comment, unlike_comment, delete_comment
 from itd.user import User
 from itd.file import CommentAttach
+if TYPE_CHECKING:
+    from itd.client import Client
 
 
 class Comment(ITDBaseModel):
@@ -130,6 +133,11 @@ class Comment(ITDBaseModel):
 
 
 class _CommentValidate(BaseModel, Comment):
+    @field_validator('attachments', mode='plain')
+    @classmethod
+    def validate_attachments(cls, attachments: list[dict]):
+        return [CommentAttach(attach) for attach in attachments]
+
     @field_validator('replies', mode='plain')
     @classmethod
     def validate_replies(cls, replies: list[dict]):

{itd_sdk-2.1.2 → itd_sdk-2.3.0}/itd/enums.py

@@ -1,6 +1,48 @@
 from enum import Enum
 from typing import Literal
 
+class InteractionType(Enum):
+    PHOTO_OPEN = 1
+    VIDEO_PROGRESS = 2
+
+class ViewSource(Enum):
+    FEED_GLOBAL = 1
+    FEED_FOLLOWING = 2
+    FEED_CLAN = 3
+    PROFILE = 4
+    HASHTAG = 5
+    POST_PAGE = 6
+    LINK = 7
+    SEARCH = 8
+
+class ViewReason(Enum):
+    NORMAL = 0 # стандартное
+    BLUR = 1 # страница скрыта (listener blur)
+    HIDDEN = 2 # тоже страница скрыта (listener visibilitychange и доп.проверка что document.hidden)
+    PAGE_HIDE = 3 # и это тоже страница скрыта (listener pagehiden)
+    UNOBSERVE = 4 # что то заумное на фронтедерском
+    THRESHOLD_MET = 5 # трэшхолд типо плавный просмотр, я не осбо понял для чего это
+
+class AuthLevel(Enum):
+    NO = 'no'
+    ACCESS = 'access'
+    REFRESH = 'refresh'
+    # LOGIN = 'login' # 🤫
+
+    def __gt__(self, other):
+        return _AUTH_LEVEL_HIERARCHY.index(self) > _AUTH_LEVEL_HIERARCHY.index(other)
+
+    def __lt__(self, other):
+        return _AUTH_LEVEL_HIERARCHY.index(self) < _AUTH_LEVEL_HIERARCHY.index(other)
+
+    def __ge__(self, other):
+        return _AUTH_LEVEL_HIERARCHY.index(self) >= _AUTH_LEVEL_HIERARCHY.index(other)
+
+    def __le__(self, other):
+        return _AUTH_LEVEL_HIERARCHY.index(self) <= _AUTH_LEVEL_HIERARCHY.index(other)
+
+_AUTH_LEVEL_HIERARCHY = [AuthLevel.NO, AuthLevel.ACCESS, AuthLevel.REFRESH]
+
 class RateLimitMode(Enum):
     NO = 'no'
     MIN = 'min' # for one-time actions (eg script just to like post)
@@ -57,7 +99,7 @@ class AttachType(Enum):
     AUDIO = 'audio'
     IMAGE = 'image'
     VIDEO = 'video'
-    FILE = 'file'
+    MEDIA = 'media'
 
 class PostsTab(Enum):
     FOLLOWING = 'following'
@@ -81,18 +123,18 @@ class AccessType(Enum):
     EVERYONE = 'everyone' # все
 
     def __gt__(self, other):
-        return _HIERARCHY.index(self) > _HIERARCHY.index(other)
+        return _ACCESS_TYPE_HIERARCHY.index(self) > _ACCESS_TYPE_HIERARCHY.index(other)
 
     def __lt__(self, other):
-        return _HIERARCHY.index(self) < _HIERARCHY.index(other)
+        return _ACCESS_TYPE_HIERARCHY.index(self) < _ACCESS_TYPE_HIERARCHY.index(other)
 
     def __ge__(self, other):
-        return _HIERARCHY.index(self) >= _HIERARCHY.index(other)
+        return _ACCESS_TYPE_HIERARCHY.index(self) >= _ACCESS_TYPE_HIERARCHY.index(other)
 
     def __le__(self, other):
-        return _HIERARCHY.index(self) <= _HIERARCHY.index(other)
+        return _ACCESS_TYPE_HIERARCHY.index(self) <= _ACCESS_TYPE_HIERARCHY.index(other)
 
-_HIERARCHY = [AccessType.EVERYONE, AccessType.FOLLOWERS, AccessType.MUTUAL, AccessType.EVERYONE] # 100% that hierarcy is spelled wrong
+_ACCESS_TYPE_HIERARCHY = [AccessType.EVERYONE, AccessType.FOLLOWERS, AccessType.MUTUAL, AccessType.EVERYONE] # 100% that hierarcy is spelled wrong
 
 
 class SpanType(Enum):

{itd_sdk-2.1.2 → itd_sdk-2.3.0}/itd/exceptions.py

@@ -2,6 +2,9 @@ from typing import Callable
 
 from requests import Response
 
+from itd.enums import AuthLevel
+
+
 class ITDException(Exception):
     code: str | None = None # ['error']['code']
     message: str | None = None # ['error']['message']
@@ -92,6 +95,21 @@ class AccessTokenExpiredError(AuthError):
     json_check = staticmethod(lambda json: json.get('error') == 'token expired')
 
 
+class LoginError(AuthError): pass
+
+class InvalidCredentials(LoginError):
+    code = 'ACCOUNT_INVALID_CREDENTIALS'
+    text = 'Invalid login credentials'
+
+class CaptchaFailedError(LoginError):
+    code = 'TURNSTILE_VERIFICATION_FAILED'
+    text = 'Captcha check failed'
+
+class EmailDomainNotAllowed(LoginError):
+    code = 'ACCOUNT_EMAIL_DOMAIN_NOT_ALLOWED'
+    text = 'Email domain not allowed'
+
+
 class PasswordError(ITDException): pass
 
 class SamePasswordError(PasswordError, ValidateError):
@@ -110,8 +128,8 @@ class InvalidPasswordError(PasswordError, ValidateError):
 class NoRightsError(ITDException): pass
 
 class InsufficientAuthLevelError(NoRightsError):
-    def __init__(self) :
-        self.text = 'Insufficient auth level'
+    def __init__(self, current: AuthLevel, requires: AuthLevel) :
+        self.text = f'Insufficient auth level (current is {current.name}, requires {requires.name})'
 
 class PinNotOwnedError(NoRightsError):
     code = "PIN_NOT_OWNED"
@@ -244,13 +262,21 @@ class TargetUserBannedError(ITDException): # target banned (eg if you try to fol
     message = 'Этот аккаунт заблокирован'
     text = 'Target user has been deactivated'
 
-class AccountBannedError(ITDException): # you are banned
-    code = 'ACCOUNT_BANNED'
+class AccountBannedError(LoginError): # you are banned
+    json_check = staticmethod(lambda json: json.get('error', {}).get('code') in ('ACCOUNT_BANNED', 'ACCOUNT_DEACTIVATED'))
     text = 'Account has been deactivated'
 
+class AccountTemporarilyBannedError(LoginError):
+    code = 'ACCOUNT_DEACTIVATED'
+    text = 'Account has been temporarily deactivated'
+
 class ProfileRequiredError(ITDException):
     code = 'PROFILE_REQUIRED'
     text = 'No profile. Please create your profile first'
 
 
-DEFAULT_ERRORS = (RateLimitError(), InvalidAccessTokenError(), UnauthorizedError(), AccessTokenExpiredError(), AccountBannedError(), InternalError(), ProfileRequiredError())
+DEFAULT_ERRORS = (
+    RateLimitError(), InvalidAccessTokenError(), UnauthorizedError(), AccessTokenExpiredError(),
+    AccountBannedError(), AccountTemporarilyBannedError(), InternalError(),
+    ProfileRequiredError(), RefreshTokenMissingError()
+)

itd_sdk-2.3.0/itd/file.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from uuid import UUID
+from os.path import basename
+from _io import BufferedReader
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+from requests import get
+
+from itd.base import ITDBaseModel, refresh_wrapper
+from itd.enums import AttachType
+from itd.api.files import upload_file, delete_file
+if TYPE_CHECKING:
+    from itd.client import Client
+    from itd.post import Post
+
+class File(ITDBaseModel):
+    _refreshable = False
+    _validator = lambda _: _FileValidate
+
+    id: UUID
+    url: str
+    filename: str
+    mime_type: str = Field(alias='mimeType')
+    size: int
+    # created_at: datetime | None = Field(None, alias='createdAt')
+
+    def __init__(self, name: str, data: bytes | BufferedReader, client: Client | None = None):
+        super().__init__(client)
+        self.filename = name
+        self._upload(data)
+
+    @classmethod
+    def from_path(cls, path: Path | str):
+        if isinstance(path, str):
+            path = Path(path)
+        return cls(path.name, path.read_bytes())
+
+    @classmethod
+    def from_bytes(cls, data: bytes | BufferedReader):
+        try:
+            from filetype import guess
+        except ModuleNotFoundError:
+            raise ImportError('filetype is required for File.from_bytes. Install by running "uv add itd-sdk[filetype]" (or "pip install itd-sdk[filetype]" if you are using pip)')
+
+        kind = guess(data)
+        return cls(
+            f'file.{kind.extension}' if kind else 'file.0',
+            data
+        )
+
+    @refresh_wrapper
+    def _upload(self, data: bytes | BufferedReader):
+        return upload_file(self.client, self.filename, data).json()
+
+    def delete(self) -> None:
+        delete_file(self.client, self.id)
+
+    def download(self, name: str | None = None) -> None:
+        with open(name or self.filename, 'wb') as fl:
+            fl.write(get(self.url, timeout=60).content)
+
+    def __str__(self) -> str:
+        return self.filename
+
+
+class _FileValidate(BaseModel, File):
+    pass
+
+
+
+class PostAttach(ITDBaseModel):
+    _validator = lambda _: _PostAttachValidate
+    _post: Post
+
+    id: UUID
+    type: AttachType = AttachType.IMAGE
+    url: str
+    thumbnail_url: str | None = Field(None, alias='thumbnailUrl')
+    width: int | None = None
+    height: int | None = None
+
+    def __init__(self, attach: dict, client: Client | None = None) -> None:
+        super().__init__(client)
+
+        for name, value in _PostAttachValidate.model_validate(attach).__dict__.items():
+            setattr(self, name, value)
+
+    def download(self, name: str) -> None:
+        """Скачать вложение
+
+        Args:
+            name (str): Имя файла.
+        """
+        with open(name, 'wb') as fl:
+            fl.write(get(self.url, timeout=self.client.config.timeout_file).content)
+
+    def record_open(self, client: Client | None = None):
+        """Записать событие открытия фото
+
+        Args:
+            client (Client | None, optional): Клиент. Defaults to None.
+        """
+        c = (client or self.client)
+        assert c.dwell_tracker is not None, 'Enable dwell to record photo opens'
+        assert self.type == AttachType.IMAGE, 'Recording photo open allowed only for images'
+        c.dwell_tracker.record_photo_open(self._post.vs, self._post.source, self.id, self._post.attachments.index(self))
+
+    def record_progress(self, duration: int, played: int | None = None, client: Client | None = None):
+        """Записать событие просмотра видео
+
+        Args:
+            duration (int): Общая длина видео (в сожалению итд не отдает, пишите сами)
+            played (int | None, optional): Сколько было просмотренно (мс). None - берется из duration. Defaults to None.
+            client (Client | None, optional): Клиент. Defaults to None.
+        """
+        c = (client or self.client)
+        assert c.dwell_tracker is not None, 'Enable dwell to record photo opens'
+        assert self.type == AttachType.VIDEO, 'Recording video progress allowed only for videos'
+        c.dwell_tracker.record_video_progress(self._post.vs, self._post.source, self.id, played or duration, duration)
+
+
+class _PostAttachValidate(BaseModel, PostAttach):
+    pass
+
+
+
+class CommentAttach(PostAttach):
+    _validator = lambda _: _CommentAttachValidate
+    filename: str
+    mime_type: str = Field(alias='mimeType')
+    size: int
+    duration: int | None = None
+    order: int = 0
+
+    def __init__(self, attach: dict, client: Client | None = None) -> None:
+        super(PostAttach, self).__init__(client)
+
+        for name, value in _CommentAttachValidate.model_validate(attach).__dict__.items():
+            setattr(self, name, value)
+
+    def record_open(self, client: Client | None = None):
+        raise AttributeError
+
+    def record_progress(self, duration: int, played: int | None = None, client: Client | None = None):
+        raise AttributeError
+
+    def download(self, name: str | None = None) -> None:
+        """Скачать вложение
+
+        Args:
+            name (str | None, optional): Имя файла. None - имя, под которым был загружен этот файл. Defaults to None.
+        """
+        with open(name or self.filename, 'wb') as fl:
+            fl.write(get(self.url, timeout=self.client.config.timeout_file).content)
+
+
+class _CommentAttachValidate(BaseModel, CommentAttach):
+    pass

{itd_sdk-2.1.2 → itd_sdk-2.3.0}/itd/post.py

@@ -1,30 +1,210 @@
-from uuid import UUID
-from datetime import datetime
+from __future__ import annotations
+from uuid import UUID, uuid4
+from datetime import datetime, timedelta
 from typing import Literal, overload, TYPE_CHECKING
 from time import sleep
+from threading import Thread
+from atexit import register
 
-from pydantic import Field, BaseModel, field_validator
+from pydantic import Field, BaseModel, field_validator, field_serializer
 
-from itd.base import ITDBaseModel, refresh_wrapper, ITDList
-from itd.client import Client
 from itd.comment import Comment, Comments
-from itd.enums import PostsTab, UserPostSorting, ReportReason, ReportTargetType, ParseMode, ALL
 from itd.file import PostAttach
 from itd.hashtag import Hashtag
 from itd.poll import Poll, NewPoll, PollOption
 from itd.report import Report
 from itd.span import Span
 from itd.user import User, _UserBase, Me
-from itd.utils import to_uuid, parse_datetime, format_attachments, ATTACHMENTS, parse_html, parse_md
+
 from itd.api.posts import (
     get_post, create_post, like_post, unlike_post, repost, view_post, pin_post, unpin_post,
     delete_post, restore_post, edit_post, get_posts, get_user_posts, get_liked_posts
 )
 from itd.api.hashtags import get_posts_by_hashtag
+from itd.api.dwell import send_views, send_interactions
+from itd.base import ITDBaseModel, refresh_wrapper, ITDList
+from itd.enums import PostsTab, UserPostSorting, ReportReason, ReportTargetType, ParseMode, ALL, ViewReason, ViewSource, InteractionType
 from itd.logger import get_logger
+from itd.utils import to_uuid, parse_datetime, format_attachments, ATTACHMENTS, parse_html, parse_md
+if TYPE_CHECKING:
+    from itd.client import Client
 
 l = get_logger('post')
 
+class DwellEvent(BaseModel):
+    vs: str = Field(alias='v')
+    source: ViewSource = Field(alias='s')
+
+
+class InteractionEvent(DwellEvent):
+    type: InteractionType = Field(alias='t')
+    attachment_id: UUID = Field(alias='ai')
+
+class PhotoOpenEvent(InteractionEvent):
+    index: int | None = Field(None, alias='mi')
+
+class VideoProgressEvent(InteractionEvent):
+    played: int = Field(alias='pm')
+    duration: int = Field(alias='dm')
+
+
+class ViewEvent(DwellEvent):
+    duration: int = Field(alias='md')
+    entered_at: int = Field(alias='et')
+    exited_at: int = Field(alias='xt')
+    reason: ViewReason = Field(alias='r')
+    source_context: str | None = Field(None, alias='sc')
+    has_seen: bool = Field(False, alias='b')
+
+    @field_serializer('has_seen', mode='plain')
+    @classmethod
+    def serialize_has_seen(cls, value: bool):
+        return int(value)
+
+
+class DwellTracker(ITDBaseModel):
+    def __init__(self, client: Client | None = None) -> None:
+        super().__init__(client)
+        self.views: list[ViewEvent] = []
+        self.interactions: list[InteractionEvent] = []
+        self.seen_posts: set[UUID] = set()
+        self.sid = uuid4()
+        self._thread: Thread | None = None
+
+    def send_views(self) -> bool: # call on app visibilitychange
+        """Отправить просмотры (api/v1/i) и очистить буффер
+
+        Returns:
+            bool: Статус (False если буффер пустой и ничего не было отправлено)
+        """
+        if not self.views:
+            return False
+        l.info('dwell send view batch')
+        send_views(self.client, [event.model_dump(mode='json', by_alias=True) for event in self.views], self.sid)
+        self.views.clear()
+        return True
+
+    def send_interactions(self) -> bool: # call on app visibilitychange
+        """Отправить события взаимодействий с вложениями (api/v1/x) и очистить буффер
+
+        Returns:
+            bool: Статус (False если буффер пустой и ничего не было отправлено)
+        """
+        if not self.interactions:
+            return False
+        l.info('dwell send interactions batch')
+        send_interactions(self.client, [event.model_dump(mode='json', by_alias=True) for event in self.interactions], self.sid)
+        self.interactions.clear()
+        return True
+
+    def record_view(self, id: UUID, vs: str, duration: int, entered_at: datetime, source: ViewSource, source_context: str | None = None, reason: ViewReason = ViewReason.NORMAL):
+        """Записать событие просмотра
+
+        Args:
+            id (UUID): ID поста
+            vs (str): VS
+            duration (int): Время на просмотр (сколько времени пользователь читал пост) (мс). Желательно должно быть 250+
+            entered_at (datetime): Дата открытия поста (когда пользователь увидел пост)
+            reason (ViewReason): Причина просмотра
+            source (ViewSource): Страница, с которой произошел просмотр
+        """
+        l.info(
+            'dwell add view record id=%s vs=%s duration=%s entered_at=%s exited_at=%s source=%s source_context=%s reason=%s',
+            id, vs, duration, entered_at.strftime('%m.%d %H:%M:%S'),
+            (entered_at + timedelta(milliseconds=duration)).strftime('%m.%d %H:%M:%S'),
+            source.value, source_context, reason.value
+        )
+
+        self.views.append(
+            ViewEvent( # stupid pydantic i want validate by name
+                v=vs,
+                md=duration,
+                et=round(entered_at.timestamp() * 1000),
+                xt=round(entered_at.timestamp() * 1000) + duration,
+                r=reason,
+                s=source,
+                sc=source_context,
+                b=id in self.seen_posts
+            )
+        )
+        self.seen_posts.add(id)
+        if len(self.views) >= self.client.config.dwell_max_buffer:
+            self.send_views()
+
+    def record_photo_open(self, vs: str, source: ViewSource, attachment_id: UUID, index: int):
+        """Записать событие просомтра фото
+
+        Args:
+            vs (str): VS
+            source (ViewSource): Страница, с которой проищошел просмотр
+            attachment_id (UUID): ID вложения
+            index (int): Индекс вложения
+        """
+        l.info('dwell add photo open record vs=%s source=%s id=%s index=%s', vs, source.value, attachment_id, index)
+
+        self.interactions.append(
+            PhotoOpenEvent(
+                v=vs,
+                s=source,
+                t=InteractionType.PHOTO_OPEN,
+                ai=attachment_id,
+                mi=index
+            )
+        )
+        if len(self.interactions) >= self.client.config.dwell_max_buffer:
+            self.send_interactions()
+
+    def record_video_progress(self, vs: str, source: ViewSource, attachment_id: UUID, played: int, duration: int):
+        """Записать событие просмотра видео (отправлять каждые 2-3 сек пока запущено видео)
+
+        Args:
+            vs (str): VS
+            source (ViewSource): Страница, с которой произошел просмотр
+            attachment_id (UUID): ID просмотренного вложения
+            played (int): Сколько было просмотренно (мс) с учетом перепросмотров
+            duration (int): Общая длительность видео (константа) (мс)
+        """
+        l.info('dwell add video progress record vs=%s source=%s id=%s played=%s duration=%s', vs, source, attachment_id, played, duration)
+
+        self.interactions.append(
+            VideoProgressEvent(
+                v=vs,
+                s=source,
+                t=InteractionType.VIDEO_PROGRESS,
+                ai=attachment_id,
+                pm=played,
+                dm=duration
+            )
+        )
+        if len(self.interactions) >= self.client.config.dwell_max_buffer:
+            self.send_interactions()
+
+
+    def _start_timer(self):
+        if not self.client.config.dwell_send_interval:
+            return
+
+        def loop():
+            while True:
+                sleep(self.client.config.dwell_send_interval)
+                self.send_views()
+                self.send_interactions()
+
+        self._thread = Thread(target=loop)
+        self._thread.daemon = True
+        self._thread.start()
+
+        def on_exit():
+            l.debug('stop dwell timer')
+            if self._thread:
+                self._thread.join(timeout=0)
+            self.send_views()
+            self.send_interactions()
+
+        if self.client.config.dwell_save_on_quit:
+            register(on_exit)
+
+
 
 class Post(ITDBaseModel):
     _validator = lambda _: _PostValidate
@@ -58,15 +238,26 @@ class Post(ITDBaseModel):
 
     wall_recipient_id: UUID | None = Field(None, alias='wallRecipientId')
     wall_recipient: User | None = Field(None, alias='wallRecipient')
+    # vs: ViewerSession
+    vs: str = Field('') # from 13.05 it is string token
 
 
-    def __init__(self, id: str | UUID, client: Client | None = None) -> None:
+    def __init__(self, id: str | UUID, source: ViewSource = ViewSource.POST_PAGE, source_context: str | None = None, client: Client | None = None) -> None:
         self.id = to_uuid(id)
+        self.source = source
+        self.source_context = source_context
+
         super().__init__(client)
 
     def for_client(self, client: Client):
         return Post(self.id, client=client)
 
+    def _post_refresh(self):
+        self.comments = Comments()
+        self.comments._post_id = self.id
+        for attachment in self.attachments:
+            attachment._post = self
+
 
     @classmethod
     def new(
@@ -117,12 +308,13 @@ class Post(ITDBaseModel):
         for name, value in validated.__dict__.items():
             setattr(instance, name, value)
 
-        instance._loaded = True
+        instance._loaded = False
+        instance._post_refresh()
 
         return instance
 
     @classmethod
-    def _from_dict(cls, data: dict, set_loaded: bool = True, client: Client | None = None) -> 'Post':
+    def _from_dict(cls, data: dict, source: ViewSource = ViewSource.POST_PAGE, source_context: str | None = None, set_loaded: bool = True, client: Client | None = None) -> 'Post':
         instance = cls.__new__(cls)
         super(Post, instance).__init__(client)
 
@@ -132,6 +324,9 @@ class Post(ITDBaseModel):
             setattr(instance, name, value)
 
         instance._loaded = set_loaded
+        instance.source = source
+        instance.source_context = source_context
+        instance._post_refresh()
         return instance
 
 
@@ -219,14 +414,21 @@ class Post(ITDBaseModel):
 
         return Post._from_dict(post, client=client)
 
-    def view(self, client: Client | None = None) -> None:
+    def view(self, client: Client | None = None, entered_at: datetime | None = None, duration: int = 250, reason: ViewReason = ViewReason.NORMAL) -> None:
         """Просмотреть пост
 
         Args:
             client (Client | None, optional): Клиент. Defaults to None.
         """
-        view_post(client or self.client, self.id)
-        if (client or self.client) == self.client:
+        c = client or self.client
+        if c.dwell_tracker is not None:
+            if self.vs is None:
+                self.refresh(c)
+                assert self.vs
+            c.dwell_tracker.record_view(self.id, self.vs, duration, entered_at or datetime.now() - timedelta(milliseconds=duration), self.source, self.source_context, reason)
+        else:
+            view_post(c, self.id)
+        if c == self.client:
             self.is_viewed = True
         # post can be already viewed, so view will not add; thats why do not change views_count
 
@@ -313,17 +515,14 @@ class Post(ITDBaseModel):
     def url(self) -> str:
         return f'https://xn--d1ah4a.com/@{self.author.username}/post/{self.id}'
 
-    if not TYPE_CHECKING:
-        def __getattribute__(self, name: str):
-            value = super().__getattribute__(name)
-            if name == 'comments' and getattr(value, '_post_id', None) is None:
-                value = Comments()
-                value._post_id = self.id
-            return value
-
 
 
 class _PostValidate(BaseModel, Post): # BaseModel MUST be first or you ll have some problems with init
+    @field_validator('attachments', mode='plain')
+    @classmethod
+    def validate_attachments(cls, attachments: list[dict]):
+        return [PostAttach(attach) for attach in attachments]
+
     @field_validator('edited_at', mode='plain')
     @classmethod
     def validate_edited_at(cls, v: str | None):
@@ -341,7 +540,7 @@ class _PostValidate(BaseModel, Post): # BaseModel MUST be first or you ll have s
     def validate_original_post(cls, post: dict | None = None):
         if post is None:
             return
-        return Post._from_dict(post, False)
+        return Post._from_dict(post, set_loaded=False)
 
     @field_validator('poll', mode='plain')
     @classmethod
@@ -370,10 +569,17 @@ class _PostValidate(BaseModel, Post): # BaseModel MUST be first or you ll have s
         if wall_recipient is not None:
             return User._from_dict(wall_recipient, False)
 
+    # @field_validator('vs', mode='plain')
+    # @classmethod
+    # def validate_vs(cls, vs: str):
+    #     return ViewerSession(decode_jwt_payload(vs))
+
 
 
 class _BasePosts(ITDList[Post]):
     _limit = 50
+    source: ViewSource
+    source_context: str | None = None
 
     @staticmethod
     def _get_cursor(data: dict):
@@ -388,7 +594,7 @@ class _BasePosts(ITDList[Post]):
         return data['posts']
 
     def _extend(self, objects: list, client: Client):
-        self.extend([Post._from_dict(post, client=client) for post in objects])
+        self.extend([Post._from_dict(post, self.source, self.source_context, client=client) for post in objects])
 
     def __setattr__(self, name: str, value) -> None:
         if name == '_client':
@@ -404,6 +610,13 @@ class Posts(_BasePosts):
     def __init__(self, tab: PostsTab = PostsTab.POPULAR, client: Client | None = None) -> None:
         super().__init__(client)
         self.tab = tab
+        match tab:
+            case PostsTab.POPULAR:
+                self.source = ViewSource.FEED_GLOBAL
+            case PostsTab.FOLLOWING:
+                self.source = ViewSource.FEED_FOLLOWING
+            case PostsTab.CLAN:
+                self.source = ViewSource.FEED_CLAN
 
     def _fetch(self, client: Client, limit: int) -> dict:
         return get_posts(client, self.cursor, limit, self.tab).json()['data']
@@ -429,6 +642,7 @@ class UserPosts(_BasePosts):
     _load_with_parent = False
     cursor: datetime | None = None
     _force_remove_pinned_post: bool = False
+    source = ViewSource.PROFILE
 
     # ! not includes posts from other users (wall posts)
     # def _get_total(self, data: dict):
@@ -446,6 +660,7 @@ class UserPosts(_BasePosts):
             raise ValueError('User must be instance of User or Me class')
 
         self.sorting = sorting # sort is busy
+        self.source_context = str(self.user.id)
 
     def _fetch(self, client: Client, limit: int) -> dict:
         if self.sorting == UserPostSorting.NEW and client.config.userposts_add_pinned_post and not self._force_remove_pinned_post:
@@ -507,6 +722,7 @@ class LikedPosts(_BasePosts): # [] if forbidden
 class HashtagPosts(_BasePosts):
     hashtag: Hashtag
     cursor: UUID | None = None
+    source = ViewSource.HASHTAG
 
     def __init__(self, hashtag: Hashtag | str, client: Client | None = None) -> None:
         super().__init__(client)
@@ -514,12 +730,13 @@ class HashtagPosts(_BasePosts):
         if isinstance(hashtag, str):
             hashtag = Hashtag(hashtag, self.client)
         self.hashtag = hashtag
+        self.source_context = self.hashtag.name
 
     def _fetch(self, client: Client, limit: int) -> dict:
         return get_posts_by_hashtag(client, self.hashtag.name, self.cursor, limit).json()['data']
 
     def _extend(self, objects: list, client: Client):
-        self.extend([Post._from_dict(post, False, client=client) for post in objects])
+        self.extend([Post._from_dict(post, self.source, self.source_context, set_loaded=False, client=client) for post in objects])
 
     def _get_total(self, data: dict):
         return data['hashtag']['postsCount']

{itd_sdk-2.1.2 → itd_sdk-2.3.0}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["uv_build"]
+requires = ["uv_build~=0.11"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
@@ -14,7 +14,7 @@ version_provider = "uv"
 
 [project]
 name = "itd-sdk"
-version = "2.1.2"
+version = "2.3.0"
 description = "ITD client for python"
 readme = "README.md"
 authors = [
@@ -25,8 +25,7 @@ classifiers = [
     'Natural Language :: Russian',
     'Programming Language :: Python',
     'Programming Language :: Python :: 3',
-    'Framework :: Pydantic :: 2',
-    'License :: OSI Approved :: MIT License'
+    'Framework :: Pydantic :: 2'
 ]
 keywords = ['itd', 'itdsocial']
 license = "MIT"

itd_sdk-2.1.2/itd/api/auth.py

@@ -1,22 +0,0 @@
-from __future__ import annotations
-from typing import TYPE_CHECKING
-
-from requests import Response
-
-from itd.base import catch_errors
-from itd.request import fetch
-from itd.exceptions import InvalidPasswordError, SamePasswordError, InvalidOldPasswordError, SessionNotFoundError, SessionExpiredError, SessionRevokedError
-if TYPE_CHECKING:
-    from itd.client import Client
-
-@catch_errors(SessionExpiredError(), SessionNotFoundError(), SessionRevokedError())
-def refresh_token(client: Client) -> Response:
-    return fetch(client, 'post', 'v1/auth/refresh')
-
-@catch_errors(InvalidPasswordError(), SamePasswordError(), InvalidOldPasswordError())
-def change_password(client: Client, old: str, new: str) -> Response:
-    return client.request('post', 'v1/auth/change-password', {'newPassword': new, 'oldPassword': old})
-
-@catch_errors()
-def logout(client: Client) -> Response:
-    return client.request('post', 'v1/auth/logout')

itd_sdk-2.1.2/itd/file.py

@@ -1,94 +0,0 @@
-from __future__ import annotations
-from typing import TYPE_CHECKING
-from uuid import UUID
-from os.path import basename
-from _io import BufferedReader
-from pathlib import Path
-
-from pydantic import BaseModel, Field
-from requests import get
-
-from itd.base import ITDBaseModel, refresh_wrapper
-from itd.enums import AttachType
-from itd.api.files import upload_file, delete_file
-if TYPE_CHECKING:
-    from itd.client import Client
-
-class File(ITDBaseModel):
-    _refreshable = False
-    _validator = lambda _: _FileValidate
-
-    id: UUID
-    url: str
-    filename: str
-    mime_type: str = Field(alias='mimeType')
-    size: int
-    # created_at: datetime | None = Field(None, alias='createdAt')
-
-    def __init__(self, name: str, data: bytes | BufferedReader, client: Client | None = None):
-        super().__init__(client)
-        self.filename = name
-        self._upload(data)
-
-    @classmethod
-    def from_path(cls, path: Path | str):
-        if isinstance(path, str):
-            path = Path(path)
-        return cls(path.name, path.read_bytes())
-
-    @classmethod
-    def from_bytes(cls, data: bytes | BufferedReader):
-        try:
-            from filetype import guess
-        except ModuleNotFoundError:
-            raise ImportError('filetype is required for File.from_bytes. Install by running "uv add itd-sdk[filetype]" (or "pip install itd-sdk[filetype]" if you are using pip)')
-
-        kind = guess(data)
-        return cls(
-            f'file.{kind.extension}' if kind else 'file.0',
-            data
-        )
-
-    @refresh_wrapper
-    def _upload(self, data: bytes | BufferedReader):
-        return upload_file(self.client, self.filename, data).json()
-
-    def delete(self) -> None:
-        delete_file(self.client, self.id)
-
-    def download(self, name: str | None = None) -> None:
-        with open(name or self.filename, 'wb') as fl:
-            fl.write(get(self.url, timeout=60).content)
-
-    def __str__(self) -> str:
-        return self.filename
-
-
-class _FileValidate(BaseModel, File):
-    pass
-
-
-
-class PostAttach(BaseModel):
-    id: UUID
-    type: AttachType = AttachType.IMAGE
-    url: str
-    thumbnail_url: str | None = Field(None, alias='thumbnailUrl')
-    width: int | None = None
-    height: int | None = None
-
-    def download(self, name: str) -> None:
-        with open(name, 'wb') as fl:
-            fl.write(get(self.url, timeout=60).content)
-
-
-class CommentAttach(PostAttach):
-    filename: str
-    mime_type: str = Field(alias='mimeType')
-    size: int
-    duration: int | None = None
-    order: int = 0
-
-    def download(self, name: str | None = None) -> None:
-        with open(name or self.filename, 'wb') as fl:
-            fl.write(get(self.url, timeout=60).content)