Metadata-Version: 2.4
Name: inscrape
Version: 0.1.0
Summary: The official Python SDK for Inscrape — the AI-first web scraping API for Instagram, X & beyond.
Project-URL: Homepage, https://inscrape.io
Project-URL: Documentation, https://docs.inscrape.io
Project-URL: Repository, https://github.com/gkhetawat1/inscrape-python
Project-URL: Issues, https://github.com/gkhetawat1/inscrape-python/issues
Project-URL: Changelog, https://github.com/gkhetawat1/inscrape-python/blob/main/CHANGELOG.md
Author-email: Ganesh Khetawat <gkhetawat1@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,inscrape,instagram,proxy,scraping,twitter,web-scraping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx<1.0.0,>=0.27.0
Provides-Extra: async
Requires-Dist: httpx[http2]<1.0.0,>=0.27.0; extra == 'async'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

# inscrape

The official Python SDK for **[Inscrape](https://inscrape.io)** — the AI-first web scraping API for Instagram, X & beyond.

[![PyPI](https://img.shields.io/pypi/v/inscrape)](https://pypi.org/project/inscrape/)
[![Python](https://img.shields.io/pypi/pyversions/inscrape)](https://pypi.org/project/inscrape/)
[![License](https://img.shields.io/pypi/l/inscrape)](https://github.com/gkhetawat1/inscrape-python/blob/main/LICENSE)

## Features

- 🚀 **3-line usage** — scrape any site with one function call
- 📸 **Screenshots** — full-page or element-targeted PNG capture
- 📝 **Markdown** — get clean Markdown instead of raw HTML
- 📊 **Structured JSON** — first-class Instagram & X/Twitter profile parsing
- ⚡ **Async support** — `AsyncInscrape` for high-concurrency workflows
- 🛡️ **Smart errors** — typed exceptions for rate limits, auth, and quota

## Installation

```bash
pip install inscrape
```

For async + HTTP/2 support:

```bash
pip install "inscrape[async]"
```

## Quick Start

```python
from inscrape import Inscrape

client = Inscrape("sk_your_token_here")

# Scrape any URL
result = client.scrape("https://example.com")
print(result.content)

# Instagram profile → structured JSON
profile = client.instagram("gkhetawat1")
print(profile["followers"])

# X/Twitter profile → structured JSON
user = client.twitter("elonmusk")
print(user["bio"])

# Full-page screenshot → PNG bytes
png = client.screenshot("https://example.com")
with open("screenshot.png", "wb") as f:
    f.write(png)

# Get Markdown
md = client.markdown("https://example.com")
print(md)
```

## Async Usage

```python
import asyncio
from inscrape import AsyncInscrape

async def main():
    client = AsyncInscrape("sk_your_token_here")

    # All methods are async
    profile = await client.instagram("gkhetawat1")
    print(profile)

    # Concurrent scraping
    results = await asyncio.gather(
        client.scrape("https://example.com"),
        client.scrape("https://httpbin.org/get"),
        client.twitter("naval"),
    )
    for r in results:
        print(r)

    await client.close()

asyncio.run(main())
```

## API Reference

### `Inscrape(token, base_url="https://api.inscrape.io")`

Create a client instance.

### `client.scrape(url, **kwargs) → ScrapeResult`

Full-parameter scrape. Pass any Inscrape API parameter as a keyword argument:

```python
result = client.scrape(
    "https://example.com",
    render=True,
    super_proxy=True,      # maps to super=true
    geo_code="IN",         # maps to geoCode=IN
    wait_selector="div.content",
    block_resources=True,
    timeout=30000,
)
print(result.content)
print(result.status_code)
print(result.credits_used)
```

### `client.instagram(username, **kwargs) → dict`

Shortcut for Instagram profiles. Automatically sets `render=True`, `super=True`, `output=json`.

### `client.twitter(username, **kwargs) → dict`

Shortcut for X/Twitter profiles. Same smart defaults.

### `client.screenshot(url, full_page=True, **kwargs) → bytes`

Returns decoded PNG bytes.

### `client.markdown(url, **kwargs) → str`

Returns clean Markdown text.

### `client.estimate(url, **kwargs) → dict`

Get estimated credit cost before scraping.

## Error Handling

```python
from inscrape import Inscrape, AuthError, RateLimitError, QuotaExhaustedError, InscrapeError

client = Inscrape("sk_xxx")

try:
    result = client.scrape("https://example.com")
except AuthError:
    print("Invalid API token")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except QuotaExhaustedError:
    print("Monthly quota used up — upgrade your plan")
except InscrapeError as e:
    print(f"Scrape failed: {e.message} (code: {e.code})")
```

## License

MIT
