Metadata-Version: 2.4
Name: radimbig-pinchana-twitter
Version: 1.0.0
Summary: Unofficial PyPI distribution of Pinchana Twitter/X scraper maintained by radimbig
Keywords: pinchana,twitter,x,scraping,media,fork,unofficial
Author: Pinchana
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: radimbig-pinchana-core
Requires-Dist: curl-cffi>=0.7.0
Requires-Dist: fastapi>=0.136.1
Requires-Dist: pydantic>=2.13.3
Requires-Dist: tenacity>=9.1.4
Requires-Dist: uvicorn>=0.46.0
Maintainer: radimbig
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/radimbig2/pinchana-twitter
Project-URL: Repository, https://github.com/radimbig2/pinchana-twitter
Project-URL: Issues, https://github.com/radimbig2/pinchana-twitter/issues
Project-URL: Upstream, https://github.com/Pinchana/pinchana-twitter
Description-Content-Type: text/markdown

# radimbig-pinchana-twitter

Unofficial PyPI distribution of the Pinchana Twitter/X scraper, maintained by
radimbig for use as both a Pinchana plugin and an importable Python package.

Original project and copyright belong to Pinchana. This fork keeps the original
logic and adds packaging metadata plus a small synchronous library wrapper.

## Strategy

1. **Primary:** X internal GraphQL (`TweetResultByRestId`) using guest token activation + CSRF (`ct0`) handling.
2. **Resilience:** Automatic VPN IP rotation via Gluetun on rate limits (429/403).
3. **Fallback:** `api.fxtwitter.com` for public tweet metadata when GraphQL is blocked.
4. **Media:** Download media to local cache and expose via `/media/twitter/{tweet_id}/{file}`.

## API

- `POST /scrape` — scrape a tweet URL
- `GET /media/twitter/{tweet_id}/{filename}` — serve cached media
- `GET /health` — VPN status

## Library Usage

Install the package:

```bash
pip install radimbig-pinchana-twitter
```

Import the package as `pinchana_twitter`:

```python
from pinchana_twitter import download_x_post_assets

result = download_x_post_assets(
    post_url="https://x.com/user/status/1234567890",
    temp_directory="./temp_videos",
    user_id=42,
    request_id="abc123",
)

print(result["text"])
print(result["author_username"])
print(result["files"])
```

The synchronous wrapper returns:

```python
{
    "text": "...",
    "author_username": "user",
    "files": [{"path": "...", "media_type": "photo"}],
}
```

Use `media_type == "photo"` for images and `media_type == "video"` for videos.

## Publishing

The package publishes to PyPI when a `v*` tag is pushed and the repository has a
`PYPI_API_TOKEN` secret configured.
