autotok 2.0.0__py3-none-any.whl

autotok/__init__.py

@@ -0,0 +1,63 @@
+"""autotok: upload and schedule TikTok videos from Python or the command line.
+
+Quick start::
+
+    import autotok
+
+    autotok.login("alice")                       # opens a browser once
+    autotok.upload_video("alice", "clip.mp4", "Hello #fyp")
+
+    client = autotok.Client.from_account("alice", proxy="http://user:pass@host:8000")
+    client.upload("clip.mp4", "Scheduled #fyp", schedule=3600)
+"""
+from __future__ import annotations
+
+__version__ = "2.0.0"
+
+from .accounts import Account, AccountStore
+from .errors import (
+    AccountNotFoundError,
+    AutotokError,
+    BrowserNotInstalledError,
+    LoginError,
+    MissingDependencyError,
+    NotLoggedInError,
+    PublishError,
+    PublishUncertainError,
+    SigningError,
+    UploadError,
+    ValidationError,
+)
+from .auth import import_session, login_interactive
+from .env import load_env
+from .proxy import Proxy, check_proxy, parse_proxy
+from .uploader import Client, UploadResult, upload_video
+
+login = login_interactive
+
+__all__ = [
+    "__version__",
+    "Account",
+    "AccountStore",
+    "Client",
+    "Proxy",
+    "UploadResult",
+    "check_proxy",
+    "import_session",
+    "load_env",
+    "login",
+    "login_interactive",
+    "parse_proxy",
+    "upload_video",
+    "AutotokError",
+    "AccountNotFoundError",
+    "BrowserNotInstalledError",
+    "LoginError",
+    "MissingDependencyError",
+    "NotLoggedInError",
+    "PublishError",
+    "PublishUncertainError",
+    "SigningError",
+    "UploadError",
+    "ValidationError",
+]

autotok/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m autotok`` — same as the ``autotok`` command.
+
+Useful on Windows when pip's Scripts folder isn't on PATH.
+"""
+from .cli import run
+
+run()

autotok/accounts.py

@@ -0,0 +1,233 @@
+"""Saved TikTok sessions.
+
+Each account is one JSON file in ``$AUTOTOK_HOME/accounts/<name>.json`` holding
+the TikTok cookies, the user agent of the browser that logged in, and the
+account's proxy. Files are written with ``0600`` permissions: a ``sessionid``
+cookie is full access to the TikTok account.
+
+Sessions saved by TiktokAutoUploader 1.x (pickled ``CookiesDir/tiktok_session-
+<name>.cookie`` files) are found automatically and migrated on first use. They
+are read with a restricted unpickler that only accepts plain data, so a
+tampered cookie file cannot execute code.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import pickle
+import re
+import tempfile
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import settings
+from .errors import AccountNotFoundError, ValidationError
+from .proxy import Proxy, parse_proxy
+
+log = logging.getLogger("autotok")
+
+SESSION_COOKIE = "sessionid"
+DATACENTER_COOKIE = "tt-target-idc"
+LEGACY_PREFIX = "tiktok_session-"
+LEGACY_SUFFIX = ".cookie"
+
+_NAME_RE = re.compile(r"^[A-Za-z0-9_.\-]{1,128}$")
+
+
+def validate_account_name(name: str) -> str:
+    if not isinstance(name, str) or not _NAME_RE.match(name) or name in (".", ".."):
+        raise ValidationError(
+            f"invalid account name {name!r}: use 1-128 letters, digits, '.', '_' or '-'"
+        )
+    return name
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+@dataclass
+class Account:
+    name: str
+    cookies: list[dict] = field(default_factory=list)
+    user_agent: str | None = None
+    proxy: str | None = None
+    created_at: str = field(default_factory=_now)
+    updated_at: str = field(default_factory=_now)
+
+    def __post_init__(self) -> None:
+        validate_account_name(self.name)
+        if self.proxy is not None:
+            parsed = parse_proxy(self.proxy)
+            self.proxy = parsed.url if parsed else None
+
+    def cookie(self, name: str) -> str | None:
+        for c in self.cookies:
+            if c.get("name") == name and c.get("value"):
+                return str(c["value"])
+        return None
+
+    @property
+    def session_id(self) -> str | None:
+        return self.cookie(SESSION_COOKIE)
+
+    @property
+    def datacenter(self) -> str | None:
+        return self.cookie(DATACENTER_COOKIE)
+
+    @property
+    def has_session(self) -> bool:
+        return self.session_id is not None
+
+    def get_proxy(self) -> Proxy | None:
+        return parse_proxy(self.proxy)
+
+    @classmethod
+    def from_session_id(cls, name: str, session_id: str, *, datacenter: str | None = None,
+                        user_agent: str | None = None, proxy: "str | Proxy | None" = None) -> "Account":
+        """Build an account from a ``sessionid`` copied out of a browser."""
+        if not session_id or not session_id.strip():
+            raise ValidationError("session id is empty")
+        cookies = [_cookie(SESSION_COOKIE, session_id.strip())]
+        if datacenter:
+            cookies.append(_cookie(DATACENTER_COOKIE, datacenter.strip()))
+        p = parse_proxy(proxy)
+        return cls(name=name, cookies=cookies, user_agent=user_agent, proxy=p.url if p else None)
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "cookies": self.cookies,
+            "user_agent": self.user_agent,
+            "proxy": self.proxy,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Account":
+        return cls(
+            name=data["name"],
+            cookies=list(data.get("cookies") or []),
+            user_agent=data.get("user_agent"),
+            proxy=data.get("proxy"),
+            created_at=data.get("created_at") or _now(),
+            updated_at=data.get("updated_at") or _now(),
+        )
+
+
+def _cookie(name: str, value: str) -> dict:
+    return {"name": name, "value": value, "domain": ".tiktok.com", "path": "/"}
+
+
+class _PlainDataUnpickler(pickle.Unpickler):
+    """Only lists/dicts/str/numbers/bools/None: refuse every class lookup."""
+
+    def find_class(self, module, name):  # noqa: D401
+        raise pickle.UnpicklingError(f"refusing to load {module}.{name} from a cookie file")
+
+
+def read_legacy_cookie_file(path: Path) -> list[dict]:
+    with open(path, "rb") as f:
+        data = _PlainDataUnpickler(f).load()
+    if not isinstance(data, list) or not all(isinstance(c, dict) for c in data):
+        raise ValueError(f"{path} is not a list of cookies")
+    return data
+
+
+class AccountStore:
+    def __init__(self, root: "str | Path | None" = None, legacy_dirs: "list[Path] | None" = None):
+        self.root = Path(root) if root else settings.accounts_dir()
+        self.legacy_dirs = settings.legacy_cookie_dirs() if legacy_dirs is None else list(legacy_dirs)
+
+    def path_for(self, name: str) -> Path:
+        return self.root / f"{validate_account_name(name)}.json"
+
+    def _legacy_path(self, name: str) -> Path | None:
+        for d in self.legacy_dirs:
+            p = d / f"{LEGACY_PREFIX}{name}{LEGACY_SUFFIX}"
+            if p.is_file():
+                return p
+        return None
+
+    def exists(self, name: str) -> bool:
+        return self.path_for(name).is_file() or self._legacy_path(name) is not None
+
+    def load(self, name: str) -> Account:
+        path = self.path_for(name)
+        if path.is_file():
+            try:
+                with open(path, encoding="utf-8") as f:
+                    return Account.from_dict(json.load(f))
+            except (ValueError, KeyError, TypeError) as exc:
+                raise ValidationError(
+                    f"account file {path} is unreadable ({exc}); log in again with --force"
+                ) from None
+        legacy = self._legacy_path(name)
+        if legacy is None:
+            raise AccountNotFoundError(
+                f"no saved session for '{name}'. Run: autotok login -n {name}"
+            )
+        try:
+            cookies = read_legacy_cookie_file(legacy)
+        except (pickle.UnpicklingError, ValueError, EOFError) as exc:
+            raise ValidationError(f"cannot migrate legacy session {legacy}: {exc}") from None
+        account = Account(name=name, cookies=cookies)
+        self.save(account)
+        log.info("Migrated legacy session %s to %s", legacy, path)
+        return account
+
+    def save(self, account: Account) -> Path:
+        self.root.mkdir(parents=True, exist_ok=True)
+        path = self.path_for(account.name)
+        account.updated_at = _now()
+        payload = json.dumps(account.to_dict(), indent=2)
+        fd, tmp = tempfile.mkstemp(prefix=".tmp-", dir=self.root)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(payload)
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, path)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+        return path
+
+    def delete(self, name: str) -> bool:
+        """Delete the saved session (and its legacy file, if any)."""
+        removed = False
+        path = self.path_for(name)
+        if path.is_file():
+            path.unlink()
+            removed = True
+        legacy = self._legacy_path(name)
+        if legacy is not None:
+            legacy.unlink()
+            removed = True
+        return removed
+
+    def list(self) -> list[str]:
+        names: set[str] = set()
+        if self.root.is_dir():
+            names.update(p.stem for p in self.root.glob("*.json") if _NAME_RE.match(p.stem))
+        for d in self.legacy_dirs:
+            if d.is_dir():
+                for p in d.iterdir():
+                    n = p.name
+                    if n.startswith(LEGACY_PREFIX) and n.endswith(LEGACY_SUFFIX):
+                        stem = n[len(LEGACY_PREFIX):-len(LEGACY_SUFFIX)]
+                        if _NAME_RE.match(stem):
+                            names.add(stem)
+        return sorted(names)
+
+    def set_proxy(self, name: str, proxy: "str | Proxy | None") -> Account:
+        account = self.load(name)
+        p = parse_proxy(proxy)
+        account.proxy = p.url if p else None
+        self.save(account)
+        return account

autotok/auth.py

@@ -0,0 +1,175 @@
+"""Logging in to TikTok and saving the session.
+
+``login_interactive`` opens a real (headed) Chromium window on TikTok's login
+page, routed through the account's proxy, and waits until TikTok sets the
+``sessionid`` cookie. The cookies and the browser's user agent are saved, so
+later uploads present the same browser identity that created the session.
+
+With a cloud browser (``AUTOTOK_BROWSER=browserbase`` or ``steel``) the
+browser runs remotely instead, and you log in through its live view link from
+your own browser.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from typing import Callable, Optional
+
+from . import settings
+from .accounts import DATACENTER_COOKIE, SESSION_COOKIE, Account, AccountStore, validate_account_name
+from .browsers import open_browser, sync_playwright
+from .errors import LoginError
+from .proxy import Proxy, parse_proxy
+
+log = logging.getLogger("autotok")
+
+REQUIRED_COOKIES = (SESSION_COOKIE, DATACENTER_COOKIE)
+
+
+def wait_for_session_cookies(
+    get_cookies: Callable[[], list[dict]],
+    *,
+    poll_interval: float = 1.0,
+    timeout: float | None = None,
+    should_stop: Optional[Callable[[], bool]] = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> list[dict]:
+    """Poll ``get_cookies`` until ``sessionid`` and ``tt-target-idc`` are set.
+
+    Returns every TikTok cookie at that moment. Raises :class:`LoginError` on
+    timeout, cancellation, or when the browser is closed.
+    """
+    start = time.monotonic()
+    while True:
+        if should_stop and should_stop():
+            raise LoginError("login cancelled")
+        try:
+            cookies = get_cookies()
+        except Exception as exc:
+            raise LoginError(f"the browser was closed before login finished ({exc})") from None
+        names = {c.get("name") for c in cookies if c.get("value")}
+        if all(n in names for n in REQUIRED_COOKIES):
+            return [c for c in cookies if "tiktok" in str(c.get("domain", ""))]
+        if timeout is not None and time.monotonic() - start > timeout:
+            raise LoginError(f"timed out after {int(timeout)}s waiting for TikTok login")
+        try:
+            sleep(poll_interval)
+        except Exception as exc:  # e.g. the user closed the browser window
+            raise LoginError(f"the browser was closed before login finished ({exc})") from None
+
+
+def _keep_login_tab_in_front(context, login_page) -> None:
+    """Cloud live views show only the login tab, so a popup (e.g. "Continue
+    with Google") would be invisible and steal focus from it. Close popups and
+    keep the login tab in front."""
+    closed = False
+    for p in list(context.pages):
+        if p is not login_page and not p.is_closed():
+            try:
+                p.close()
+                closed = True
+            except Exception:  # pragma: no cover - best effort
+                pass
+    if closed:
+        log.warning("Closed a popup window: popups (e.g. 'Continue with Google') can't be shown in "
+                    "the live view. Log in with the QR code, email/username or phone instead.")
+        try:
+            login_page.bring_to_front()
+        except Exception:  # pragma: no cover
+            pass
+
+
+def _announce_live_view(url: str) -> None:
+    log.warning("Open this link in your browser and log in to TikTok there:\n  %s", url)
+
+
+def open_login_session(
+    *,
+    proxy: "str | Proxy | None" = None,
+    timeout: float | None = 600,
+    should_stop: Optional[Callable[[], bool]] = None,
+    on_live_url: Optional[Callable[[str], None]] = None,
+) -> tuple[list[dict], str]:
+    """Open a browser for the user to log in. Returns ``(cookies, user_agent)``.
+
+    Shared by the CLI and the Docker web app's virtual browser. For cloud
+    browsers, ``on_live_url`` receives the link the user logs in through
+    (default: it is logged).
+    """
+    from playwright.sync_api import Error as PlaywrightError
+
+    p = parse_proxy(proxy)
+    with sync_playwright() as pw:
+        session_timeout = (timeout or 3600) + 300
+        handle = open_browser(pw, headless=False, proxy=p, args=["--start-maximized"], timeout=session_timeout)
+        try:
+            if handle.is_remote:
+                context = handle.context()
+                page = handle.page(context)
+            else:
+                context = handle.context(no_viewport=True)
+                page = context.new_page()
+            try:
+                page.goto(settings.TIKTOK_LOGIN_URL, wait_until="domcontentloaded", timeout=60_000)
+                user_agent = page.evaluate("() => navigator.userAgent")
+            except PlaywrightError as exc:
+                hint = " (check the proxy)" if p else ""
+                raise LoginError(f"could not open TikTok's login page{hint}: {exc.message}") from None
+            if handle.is_remote:
+                (on_live_url or _announce_live_view)(handle.live_view_url())
+
+            def get_cookies() -> list[dict]:
+                if page.is_closed():
+                    raise RuntimeError("page closed")
+                if handle.is_remote:
+                    _keep_login_tab_in_front(context, page)
+                return context.cookies()
+
+            cookies = wait_for_session_cookies(
+                get_cookies,
+                timeout=timeout,
+                should_stop=should_stop,
+                # Keep Playwright's event loop running while we wait.
+                sleep=lambda s: page.wait_for_timeout(s * 1000),
+            )
+        finally:
+            handle.close()
+    return cookies, user_agent
+
+
+def login_interactive(
+    name: str,
+    *,
+    proxy: "str | Proxy | None" = None,
+    timeout: float | None = 600,
+    store: AccountStore | None = None,
+    on_live_url: Optional[Callable[[str], None]] = None,
+) -> Account:
+    """Log in through a browser window and save the session as ``name``.
+
+    With a cloud browser, ``on_live_url`` gets the link to log in through.
+    """
+    validate_account_name(name)
+    p = parse_proxy(proxy)
+    cookies, user_agent = open_login_session(proxy=p, timeout=timeout, on_live_url=on_live_url)
+    account = Account(name=name, cookies=cookies, user_agent=user_agent, proxy=p.url if p else None)
+    (store or AccountStore()).save(account)
+    log.info("Saved session for '%s'", name)
+    return account
+
+
+def import_session(
+    name: str,
+    session_id: str,
+    *,
+    datacenter: str | None = None,
+    user_agent: str | None = None,
+    proxy: "str | Proxy | None" = None,
+    store: AccountStore | None = None,
+) -> Account:
+    """Save a ``sessionid`` copied from a browser's cookies (no browser needed)."""
+    account = Account.from_session_id(
+        name, session_id, datacenter=datacenter, user_agent=user_agent, proxy=proxy
+    )
+    (store or AccountStore()).save(account)
+    return account

autotok/browsers/__init__.py

@@ -0,0 +1,90 @@
+"""Where login and signing browsers run.
+
+A small factory picks the :class:`BrowserProvider` named by ``AUTOTOK_BROWSER``:
+
+* ``local``: Chromium on this machine (default)
+* ``browserbase``: Browserbase cloud browsers (``BROWSERBASE_API_KEY``)
+* ``steel``: Steel Cloud, or a self-hosted steel-browser server (``STEEL_BASE_URL``)
+
+Add your own with :func:`register_provider`::
+
+    from autotok.browsers import CloudProvider, register_provider
+
+    class MyProvider(CloudProvider):
+        label = "My cloud"
+        def create_session(self, *, proxy=None, timeout=None): ...
+
+    register_provider("mycloud", MyProvider)   # then AUTOTOK_BROWSER=mycloud
+"""
+from __future__ import annotations
+
+from typing import Callable
+
+from .. import settings
+from ..errors import ConfigurationError, MissingDependencyError
+from ..proxy import Proxy
+from .base import BrowserHandle, BrowserProvider, CloudProvider, CloudSession
+from .browserbase import BrowserbaseProvider
+from .local import LocalProvider, install_browser, launch_chromium
+from .steel import SteelProvider
+
+_REGISTRY: dict[str, Callable[[], BrowserProvider]] = {
+    "local": LocalProvider,
+    "browserbase": BrowserbaseProvider,
+    "steel": SteelProvider,
+}
+
+
+def register_provider(name: str, factory: Callable[[], BrowserProvider]) -> None:
+    """Make ``factory`` available as ``AUTOTOK_BROWSER=<name>``."""
+    _REGISTRY[name.strip().lower()] = factory
+
+
+def available_providers() -> list[str]:
+    return sorted(_REGISTRY)
+
+
+def get_provider(name: str | None = None) -> BrowserProvider:
+    """The provider called ``name``, or the one ``AUTOTOK_BROWSER`` selects."""
+    key = (name or settings.browser_provider()).strip().lower()
+    try:
+        factory = _REGISTRY[key]
+    except KeyError:
+        raise ConfigurationError(
+            f"unknown browser provider {key!r}; use one of: {', '.join(available_providers())}"
+        ) from None
+    return factory()
+
+
+def open_browser(pw, *, headless: bool = True, proxy: Proxy | None = None,
+                 args: list[str] | None = None, offline: bool = False,
+                 timeout: float | None = None, provider: str | None = None) -> BrowserHandle:
+    """Start a browser from the selected provider (see :meth:`BrowserProvider.open`)."""
+    return get_provider(provider).open(pw, headless=headless, proxy=proxy, args=args,
+                                       offline=offline, timeout=timeout)
+
+
+def sync_playwright():
+    try:
+        from playwright.sync_api import sync_playwright as _sp
+    except ImportError as exc:  # pragma: no cover - playwright is a core dependency
+        raise MissingDependencyError("playwright is not installed: pip install autotok") from exc
+    return _sp()
+
+
+__all__ = [
+    "BrowserHandle",
+    "BrowserProvider",
+    "CloudProvider",
+    "CloudSession",
+    "BrowserbaseProvider",
+    "LocalProvider",
+    "SteelProvider",
+    "available_providers",
+    "get_provider",
+    "install_browser",
+    "launch_chromium",
+    "open_browser",
+    "register_provider",
+    "sync_playwright",
+]

autotok/browsers/base.py

@@ -0,0 +1,112 @@
+"""The browser provider interface.
+
+A :class:`BrowserProvider` starts a browser and returns a :class:`BrowserHandle`.
+:class:`CloudProvider` covers services that hand out a remote Chromium over
+CDP (Browserbase, Steel): subclasses only implement :meth:`create_session`.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..errors import RemoteBrowserError
+from ..proxy import Proxy
+
+
+class CloudSession(ABC):
+    """A remote browser session."""
+
+    id: str
+    connect_url: str  # CDP endpoint for Playwright's connect_over_cdp
+
+    @abstractmethod
+    def live_view_url(self) -> str:
+        """Link that lets a person watch and control the browser."""
+
+    @abstractmethod
+    def release(self) -> None:
+        """End the session now (stops billing). Must not raise."""
+
+
+class BrowserHandle:
+    """A running browser: local Chromium, or a cloud session."""
+
+    def __init__(self, browser, *, session: CloudSession | None = None, provider: str = "local"):
+        self.browser = browser
+        self.session = session
+        self.provider = provider
+
+    @property
+    def is_remote(self) -> bool:
+        return self.session is not None
+
+    def context(self, **options):
+        """A browser context to work in. Cloud sessions come with one
+        preconfigured context (fingerprint, proxy), so ``options`` only apply
+        to local browsers."""
+        if self.is_remote:
+            return self.browser.contexts[0] if self.browser.contexts else self.browser.new_context()
+        return self.browser.new_context(**options)
+
+    @staticmethod
+    def page(context):
+        """The context's first page (cloud sessions open with one), or a new one."""
+        return context.pages[0] if context.pages else context.new_page()
+
+    def live_view_url(self) -> str | None:
+        return self.session.live_view_url() if self.session is not None else None
+
+    def close(self) -> None:
+        try:
+            self.browser.close()
+        except Exception:  # pragma: no cover - best effort cleanup
+            pass
+        if self.session is not None:
+            self.session.release()
+
+    def __enter__(self) -> "BrowserHandle":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+class BrowserProvider(ABC):
+    """Starts browsers for login and signing."""
+
+    #: Human-readable name used in messages.
+    label: str = "browser"
+
+    @abstractmethod
+    def open(self, pw, *, headless: bool = True, proxy: Proxy | None = None,
+             args: list[str] | None = None, offline: bool = False,
+             timeout: float | None = None) -> BrowserHandle:
+        """Start a browser.
+
+        ``proxy`` routes its traffic through the account's proxy. ``offline``
+        browsers only run page scripts (every request is fulfilled by a route
+        handler), so they need no proxy. ``timeout`` (seconds) bounds how long
+        a cloud session may live.
+        """
+
+
+class CloudProvider(BrowserProvider):
+    """A provider that hands out remote Chromium sessions over CDP."""
+
+    @abstractmethod
+    def create_session(self, *, proxy: Proxy | None = None, timeout: float | None = None,
+                       offline: bool = False) -> CloudSession:
+        """Start a remote session (its traffic goes through ``proxy`` if given).
+
+        ``offline`` sessions only run page scripts, so providers should skip
+        any managed proxy for them."""
+
+    def open(self, pw, *, headless: bool = True, proxy: Proxy | None = None,
+             args: list[str] | None = None, offline: bool = False,
+             timeout: float | None = None) -> BrowserHandle:
+        session = self.create_session(proxy=None if offline else proxy, timeout=timeout, offline=offline)
+        try:
+            browser = pw.chromium.connect_over_cdp(session.connect_url)
+        except Exception as exc:
+            session.release()
+            raise RemoteBrowserError(f"could not connect to the {self.label} session: {exc}") from None
+        return BrowserHandle(browser, session=session, provider=self.label)