Metadata-Version: 2.4
Name: videocensor
Version: 1.0.0
Summary: Official Python SDK for VideoCensor content moderation API — profanity detection, hate speech, censoring for text, audio and video.
Project-URL: Homepage, https://videocensor.ru/developers
Project-URL: Documentation, https://videocensor.ru/developers/docs
Project-URL: Repository, https://github.com/dzhumaevn/videocensor
Project-URL: Issues, https://videocensor.ru/developers
Author-email: VideoCensor <support@videocensor.ru>
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,audio,censor,content-moderation,moderation,profanity,profanity-filter,sdk,speech-to-text,video,videocensor
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# videocensor

Python SDK for [VideoCensor](https://videocensor.ru) content moderation API.

## Installation

```bash
pip install videocensor
```

## Quick Start

```python
from videocensor import VideoCensor

with VideoCensor(api_key="vc_live_...") as client:
    # Analyze text
    result = client.analyze_text("some text to check")
    print(result.flagged_count, result.categories)

    # Censor text
    censored = client.censor_text("some text to censor")
    print(censored.censored)

    # Analyze media file
    job = client.analyze_media("/path/to/video.mp4")
    completed = client.wait_for_job(job.id)
    analysis = client.get_job_result(completed.id)

    # Censor media from URL
    censor_job = client.censor_media_url("https://youtube.com/watch?v=...")
    done = client.wait_for_job(censor_job.id)
    client.download_job(done.id, "./censored.mp4")
```

## Async Client

```python
from videocensor import AsyncVideoCensor

async with AsyncVideoCensor(api_key="vc_live_...") as client:
    result = await client.analyze_text("some text")
    job = await client.analyze_media("/path/to/file.mp4")
    completed = await client.wait_for_job(job.id)
```

## Configuration

```python
client = VideoCensor(
    api_key="vc_live_...",                          # Required. Use vc_test_ for sandbox.
    base_url="https://videocensor.ru/api/v1",       # Optional
    timeout=30.0,                                    # Optional (seconds)
    max_retries=3,                                   # Optional
)
```

## API

### Text

| Method | Description |
|--------|-------------|
| `analyze_text(text, *, language, categories, preset)` | Analyze text |
| `censor_text(text, *, language, replacement, categories, preset)` | Censor text |

### Media

| Method | Description |
|--------|-------------|
| `analyze_media(file, *, language, mode, categories, preset)` | Upload and analyze |
| `censor_media(file, *, language, mode, way_of_blocking, ...)` | Upload and censor |
| `analyze_media_url(url, *, ...)` | Analyze from URL |
| `censor_media_url(url, *, ...)` | Censor from URL |

### Jobs

| Method | Description |
|--------|-------------|
| `list_jobs(*, page, limit, status)` | List jobs |
| `get_job(job_id)` | Get job status |
| `get_job_result(job_id)` | Get full result |
| `cancel_job(job_id)` | Cancel job |
| `download_job(job_id, output_path)` | Download file |
| `get_transcript(job_id, fmt)` | Get transcription |
| `wait_for_job(job_id, *, timeout, poll_interval)` | Poll until done |

### Batch, Webhooks, Account

| Method | Description |
|--------|-------------|
| `create_batch(requests)` | Submit batch |
| `get_batch(batch_id)` | Get batch result |
| `list_webhooks()` | List endpoints |
| `create_webhook(url, events)` | Create endpoint |
| `delete_webhook(webhook_id)` | Delete endpoint |
| `get_account()` | Account info |

## Error Handling

```python
from videocensor import VideoCensorError, RateLimitError, AuthenticationError

try:
    result = client.analyze_text("test")
except RateLimitError as e:
    print(f"Retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
```

## Content Categories

`profanity`, `hate_speech`, `extremism`, `drugs`, `sexual`, `insults`

## Requirements

Python >= 3.10, httpx >= 0.25

## Versioning

This SDK follows [SemVer](https://semver.org/):

- **MAJOR** — breaking changes (removed endpoints/fields, type changes). Deprecation notice at least 3 months in advance.
- **MINOR** — new endpoints or optional fields.
- **PATCH** — bugfixes, retry/backoff improvements, docs.

See [CHANGELOG.md](./CHANGELOG.md) for release notes.
