Metadata-Version: 2.5
Name: tikstractormf
Version: 1.6.0
Summary: Python library for TikTok - media download by post_id with Netscape cookies auth (gallery-dl compatible)
Project-URL: Homepage, https://github.com/ExtractorsMF/TikstractorMF
Project-URL: Repository, https://github.com/ExtractorsMF/TikstractorMF
Author: ExtractorsMF
License: GPL-3.0-only
License-File: LICENSE
Keywords: downloader,gallery-dl,scraper,tiktok,yt-dlp
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Requires-Dist: browser-cookie3>=0.20
Requires-Dist: curl-cffi>=0.7
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: pydantic>=2.6
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Provides-Extra: antibot
Provides-Extra: browser
Requires-Dist: playwright>=1.43; extra == 'browser'
Provides-Extra: dev
Requires-Dist: gitpython<3.1.60; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: python-semantic-release<10,>=9; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# tikstractormf

TikTok media downloader — Python library + CLI, gallery-dl/yt-dlp compatible cookies.

## Project memory

- Index: this README + `docs/` + `docs/memory/`.
- Compact memory: `docs/memory/architecture.md`, `docs/memory/decisions.md`, `docs/memory/state.md`, `docs/memory/conventions.md`, `docs/memory/testing.md`.
- Detailed docs: `docs/ARCHITECTURE.md`, `docs/DEVELOPMENT.md`, `docs/SECURITY.md`, `docs/PRIVACY.md`, `docs/GIT_WORKFLOW.md`, `docs/DECISIONS.md`.
- LLM indexes: `llms.txt`, `llms-full.txt`.
- Agent instructions: `../AGENTS.md` (workspace root).
- Last documentation review: 2026-11-03.

## Stack

Python ≥ 3.10, `httpx[http2]`, `pydantic`, `typer`, `rich`. Core: `curl_cffi` (antibot), `browser-cookie3` (browser cookies). Optional: `playwright` (not used by core paths).

## Install

```bash
uv pip install -e ".[dev]"          # dev
uv pip install -e ".[antibot]"      # TLS impersonation
uv pip install -e ".[browser]"      # Playwright + cookies
```

## Quickstart

Library:

```python
from tikstractormf import Tiktokscraper
scraper = Tiktokscraper(cookies="cookies.txt")
posts = scraper.get_posts("user", limit=20)
for post in posts:
    for media in post.media:
        scraper.download(media, dest="./dl", username=post.username, date_iso=post.datetime_iso)
scraper.download_profile_pic("user", dest="./dl")
```

CLI:

```bash
tikstractormf --cookies cookies.txt --dest ./dl @user
tikstractormf --cookies-from-browser brave --dest ./dl @user
tikstractormf --cookies cookies.txt --limit 50 --dest ./dl @user
tikstractormf --cookies cookies.txt --get-urls --dest ./dl @user
tikstractormf --cookies cookies.txt --dest ./dl @user --include posts --include profile
tikstractormf --cookies cookies.txt --dest ./dl @user --stories-only
tikstractormf --version
```

## Modules

| Module | Responsibility |
|---|---|
| client.py | Facade, wiring, download orchestration |
| api.py | Profile resolution + item_list walk + post rehydration |
| _backend.py | httpx/curl_cffi backends |
| auth.py | Netscape/browser cookies |
| models.py | Post/Media/Profile |
| template.py | Filename/directory rendering |
| rate_limit.py | Cooldowns + backoff |
| archive.py | Download ledger |
| downloader.py | CDN download + adoption |
| cli.py | Typer CLI |

## Docker

Published to GitHub Container Registry (GHCR) on every push to `main`:

```bash
# slim (~150 MB): core only, fast GraphQL path
docker pull ghcr.io/extractorsmf/tikstractormf:slim

# full (~1 GB): slim + antibot (curl_cffi) + browser (Playwright)
docker pull ghcr.io/extractorsmf/tikstractormf:full   # also tagged :latest
docker pull ghcr.io/extractorsmf/tikstractormf:1.2.0
```

Run (mount cookies and destination as volumes; never bake secrets into the image):

```bash
docker run --rm \\
  -v $(pwd)/cookies.txt:/cookies.txt:ro \\
  -v $(pwd)/dl:/dl \\
  ghcr.io/extractorsmf/tikstractormf:full \\
  --cookies /cookies.txt --dest /dl @user
```

- `TIKTOK_USE_SANDBOX=1` is set in the `full` image so Playwright works unprivileged.
- Multi-arch: `linux/amd64`, `linux/arm64`.

## Install from PyPI

```bash
pip install tikstractormf
pip install 'tikstractormf[browser]'
pip install 'tikstractormf[antibot]'
```

## Essential commands

```bash
uv run pytest -q
uv run ruff check .
uv run mypy tikstractormf scripts
```

## Key constraints

- Ledger opt-in (`--archive`); keyed by `(post_id, index)`.
- Browser fallback runs anonymously.
- GraphQL doc_id is discovered, not hardcoded.
- stdout = one line per downloaded file; diagnostics on stderr.
- Do not commit secrets or personal identities.

## More details

- Usage/CLI details: `docs/DEVELOPMENT.md` (commands), `docs/ARCHITECTURE.md` (flow).
- Security/privacy: `docs/SECURITY.md`, `docs/PRIVACY.md`.
- Git/commits: `docs/GIT_WORKFLOW.md`.
- Decisions: `docs/DECISIONS.md`.
- Known issues/state: `docs/memory/state.md`.

## Status

37 tests pass; ruff and mypy clean. Known gaps: profile-pic ext derivation, URL freshness on large profiles. See `review.md`.
