# Respectify Python Client
[](https://badge.fury.io/py/respectify)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A Python client library for the [Respectify API](https://respectify.ai), providing both synchronous and asynchronous interfaces for comment moderation, spam detection, toxicity analysis, and dogwhistle detection.
## Features
- **🔄 Dual Interface**: Both synchronous (`RespectifyClient`) and asynchronous (`RespectifyAsyncClient`) clients
- **🛡️ Type Safety**: Full type hints with Pydantic schema validation
- **📊 Comprehensive**: All Respectify API endpoints supported
- **⚡ Efficient**: Megacall support for multiple analyses in single requests
- **🚨 Error Handling**: Custom exception classes for different API error conditions
- **🐍 Modern Python**: Uses httpx for HTTP requests, beartype for runtime type checking
## Installation
```bash
pip install respectify
```
## Quick Start
### Synchronous Client
```python
from respectify import RespectifyClient
# Initialize client
client = RespectifyClient(
email="your-email@example.com",
api_key="your-api-key"
)
# Initialize a topic
topic = client.init_topic_from_text("This is my article content")
article_id = topic.article_id
# Check if a comment is spam
spam_result = client.check_spam("Great post!", article_id)
print(f"Is spam: {spam_result.is_spam}")
# Evaluate comment quality and toxicity
score = client.evaluate_comment("This is a thoughtful comment", article_id)
print(f"Quality: {score.overall_score}/5, Toxicity: {score.toxicity_score:.2f}")
```
### Asynchronous Client
```python
import asyncio
from respectify import RespectifyAsyncClient
async def main():
client = RespectifyAsyncClient(
email="your-email@example.com",
api_key="your-api-key"
)
# Initialize topic
topic = await client.init_topic_from_text("Article content")
article_id = topic.article_id
# Run multiple analyses concurrently
spam_task = client.check_spam("Great post!", article_id)
score_task = client.evaluate_comment("Thoughtful comment", article_id)
spam_result, score_result = await asyncio.gather(spam_task, score_task)
print(f"Spam: {spam_result.is_spam}, Quality: {score_result.overall_score}/5")
asyncio.run(main())
```
### Megacall for Efficiency
Perform multiple analyses in a single API call:
```python
# Instead of multiple separate calls...
result = client.megacall(
comment="Test comment",
article_id=article_id,
include_spam=True,
include_relevance=True,
include_comment_score=True,
include_dogwhistle=True
)
# Access individual results
print(f"Spam: {result.spam.is_spam if result.spam else 'N/A'}")
print(f"Quality: {result.comment_score.overall_score if result.comment_score else 'N/A'}/5")
print(f"On topic: {result.relevance.on_topic.is_on_topic if result.relevance else 'N/A'}")
print(f"Dogwhistles: {result.dogwhistle.detection.dogwhistles_detected if result.dogwhistle else 'N/A'}")
```
## API Reference
### Available Methods
**Topic Management:**
- `init_topic_from_text(text, topic_description=None)` - Initialize topic from text content
- `init_topic_from_url(url, topic_description=None)` - Initialize topic from URL
**Comment Analysis:**
- `check_spam(comment, article_id)` - Spam detection
- `evaluate_comment(comment, article_id)` - Quality scoring and toxicity analysis
- `check_relevance(comment, article_id, banned_topics=None)` - Relevance and banned topic detection
- `check_dogwhistle(comment, sensitive_topics=None, dogwhistle_examples=None)` - Dogwhistle detection
**Batch Operations:**
- `megacall(comment, article_id, **options)` - Multiple analyses in one call
**Authentication:**
- `check_user_credentials()` - Verify API credentials
### Response Schemas
All API responses are parsed into strongly-typed Pydantic models:
- `InitTopicResponse` - Topic initialization result
- `SpamDetectionResult` - Spam analysis with confidence scores
- `CommentScore` - Quality metrics and toxicity analysis
- `CommentRelevanceResult` - Topic relevance and banned topic detection
- `DogwhistleResult` - Dogwhistle detection with detailed analysis
- `MegaCallResult` - Container for multiple analysis results
- `UserCheckResponse` - Authentication verification result
### Error Handling
```python
from respectify import (
RespectifyError, # Base exception
AuthenticationError, # Invalid credentials (401)
BadRequestError, # Invalid parameters (400)
PaymentRequiredError, # Subscription required (402)
ServerError # Server issues (500+)
)
try:
result = client.check_spam("test", article_id)
except AuthenticationError:
print("Please check your API credentials")
except PaymentRequiredError:
print("This feature requires a paid plan")
except BadRequestError as e:
print(f"Invalid request: {e.message}")
```
## Configuration
### Environment Variables
Create a `.env` file for testing:
```bash
RESPECTIFY_EMAIL=your-email@example.com
RESPECTIFY_API_KEY=your-api-key
RESPECTIFY_BASE_URL=https://app.respectify.org # Optional
REAL_ARTICLE_ID=your-test-article-uuid # Optional
```
### Client Options
```python
client = RespectifyClient(
email="your-email@example.com",
api_key="your-api-key",
base_url="https://app.respectify.org", # Optional, defaults to production
version="0.2", # Optional, API version
timeout=30.0 # Optional, request timeout in seconds
)
```
## Development
### Running Tests
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests with real API (requires .env file)
pytest tests/ -v
# Run tests with coverage
pytest tests/ --cov=respectify --cov-report=html
```
### Building Documentation
```bash
# Install documentation dependencies
pip install -e ".[docs]"
# Build documentation
cd docs
make html
# Serve documentation locally
python -m http.server 8000 --directory _build/html
```
### Code Quality
```bash
# Run ruff linting and formatting
ruff check respectify/
ruff format respectify/
# Beartype provides runtime type checking automatically
# No separate type checking step needed!
```
## Requirements
- Python 3.9+
- httpx >= 0.24.0
- pydantic >= 2.0.0
- beartype >= 0.15.0
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **Documentation**: [Full API documentation](https://docs.respectify.org)
- **Issues**: [GitHub Issues](https://github.com/respectify/respectify-python/issues)
- **Website**: [Respectify.ai](https://respectify.ai)
## Changelog
### v0.1.0 (2025-01-XX)
- Initial release
- Synchronous and asynchronous client support
- Complete API coverage for all Respectify endpoints
- Comprehensive type safety with Pydantic schemas
- Megacall support for efficient batch operations
- Full test suite with real API integration
- Sphinx documentation with examples
Raw data
{
"_id": null,
"home_page": null,
"name": "respectify",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "abuse-detection, api, civility, comment, content-filtering, discourse, discussion, dogwhistle, moderation, respectify, spam, toxicity",
"author": null,
"author_email": "Respectify <dave@respectify.ai>",
"download_url": "https://files.pythonhosted.org/packages/72/72/4c2f406ed2afea536e5922af79b9a4b797e13812d311b162cb17877ae30b/respectify-0.1.0.tar.gz",
"platform": null,
"description": "# Respectify Python Client\n\n[](https://badge.fury.io/py/respectify)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA Python client library for the [Respectify API](https://respectify.ai), providing both synchronous and asynchronous interfaces for comment moderation, spam detection, toxicity analysis, and dogwhistle detection.\n\n## Features\n\n- **\ud83d\udd04 Dual Interface**: Both synchronous (`RespectifyClient`) and asynchronous (`RespectifyAsyncClient`) clients\n- **\ud83d\udee1\ufe0f Type Safety**: Full type hints with Pydantic schema validation \n- **\ud83d\udcca Comprehensive**: All Respectify API endpoints supported\n- **\u26a1 Efficient**: Megacall support for multiple analyses in single requests\n- **\ud83d\udea8 Error Handling**: Custom exception classes for different API error conditions\n- **\ud83d\udc0d Modern Python**: Uses httpx for HTTP requests, beartype for runtime type checking\n\n## Installation\n\n```bash\npip install respectify\n```\n\n## Quick Start\n\n### Synchronous Client\n\n```python\nfrom respectify import RespectifyClient\n\n# Initialize client\nclient = RespectifyClient(\n email=\"your-email@example.com\",\n api_key=\"your-api-key\"\n)\n\n# Initialize a topic\ntopic = client.init_topic_from_text(\"This is my article content\")\narticle_id = topic.article_id\n\n# Check if a comment is spam\nspam_result = client.check_spam(\"Great post!\", article_id)\nprint(f\"Is spam: {spam_result.is_spam}\")\n\n# Evaluate comment quality and toxicity\nscore = client.evaluate_comment(\"This is a thoughtful comment\", article_id)\nprint(f\"Quality: {score.overall_score}/5, Toxicity: {score.toxicity_score:.2f}\")\n```\n\n### Asynchronous Client\n\n```python\nimport asyncio\nfrom respectify import RespectifyAsyncClient\n\nasync def main():\n client = RespectifyAsyncClient(\n email=\"your-email@example.com\",\n api_key=\"your-api-key\"\n )\n \n # Initialize topic\n topic = await client.init_topic_from_text(\"Article content\")\n article_id = topic.article_id\n \n # Run multiple analyses concurrently\n spam_task = client.check_spam(\"Great post!\", article_id)\n score_task = client.evaluate_comment(\"Thoughtful comment\", article_id)\n \n spam_result, score_result = await asyncio.gather(spam_task, score_task)\n \n print(f\"Spam: {spam_result.is_spam}, Quality: {score_result.overall_score}/5\")\n\nasyncio.run(main())\n```\n\n### Megacall for Efficiency\n\nPerform multiple analyses in a single API call:\n\n```python\n# Instead of multiple separate calls...\nresult = client.megacall(\n comment=\"Test comment\",\n article_id=article_id,\n include_spam=True,\n include_relevance=True, \n include_comment_score=True,\n include_dogwhistle=True\n)\n\n# Access individual results\nprint(f\"Spam: {result.spam.is_spam if result.spam else 'N/A'}\")\nprint(f\"Quality: {result.comment_score.overall_score if result.comment_score else 'N/A'}/5\")\nprint(f\"On topic: {result.relevance.on_topic.is_on_topic if result.relevance else 'N/A'}\")\nprint(f\"Dogwhistles: {result.dogwhistle.detection.dogwhistles_detected if result.dogwhistle else 'N/A'}\")\n```\n\n## API Reference\n\n### Available Methods\n\n**Topic Management:**\n- `init_topic_from_text(text, topic_description=None)` - Initialize topic from text content\n- `init_topic_from_url(url, topic_description=None)` - Initialize topic from URL\n\n**Comment Analysis:**\n- `check_spam(comment, article_id)` - Spam detection\n- `evaluate_comment(comment, article_id)` - Quality scoring and toxicity analysis \n- `check_relevance(comment, article_id, banned_topics=None)` - Relevance and banned topic detection\n- `check_dogwhistle(comment, sensitive_topics=None, dogwhistle_examples=None)` - Dogwhistle detection\n\n**Batch Operations:**\n- `megacall(comment, article_id, **options)` - Multiple analyses in one call\n\n**Authentication:**\n- `check_user_credentials()` - Verify API credentials\n\n### Response Schemas\n\nAll API responses are parsed into strongly-typed Pydantic models:\n\n- `InitTopicResponse` - Topic initialization result\n- `SpamDetectionResult` - Spam analysis with confidence scores\n- `CommentScore` - Quality metrics and toxicity analysis\n- `CommentRelevanceResult` - Topic relevance and banned topic detection \n- `DogwhistleResult` - Dogwhistle detection with detailed analysis\n- `MegaCallResult` - Container for multiple analysis results\n- `UserCheckResponse` - Authentication verification result\n\n### Error Handling\n\n```python\nfrom respectify import (\n RespectifyError, # Base exception\n AuthenticationError, # Invalid credentials (401)\n BadRequestError, # Invalid parameters (400)\n PaymentRequiredError, # Subscription required (402)\n ServerError # Server issues (500+)\n)\n\ntry:\n result = client.check_spam(\"test\", article_id)\nexcept AuthenticationError:\n print(\"Please check your API credentials\")\nexcept PaymentRequiredError:\n print(\"This feature requires a paid plan\")\nexcept BadRequestError as e:\n print(f\"Invalid request: {e.message}\")\n```\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file for testing:\n\n```bash\nRESPECTIFY_EMAIL=your-email@example.com\nRESPECTIFY_API_KEY=your-api-key\nRESPECTIFY_BASE_URL=https://app.respectify.org # Optional\nREAL_ARTICLE_ID=your-test-article-uuid # Optional\n```\n\n### Client Options\n\n```python\nclient = RespectifyClient(\n email=\"your-email@example.com\",\n api_key=\"your-api-key\",\n base_url=\"https://app.respectify.org\", # Optional, defaults to production\n version=\"0.2\", # Optional, API version\n timeout=30.0 # Optional, request timeout in seconds\n)\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests with real API (requires .env file)\npytest tests/ -v\n\n# Run tests with coverage\npytest tests/ --cov=respectify --cov-report=html\n```\n\n### Building Documentation\n\n```bash\n# Install documentation dependencies \npip install -e \".[docs]\"\n\n# Build documentation\ncd docs\nmake html\n\n# Serve documentation locally\npython -m http.server 8000 --directory _build/html\n```\n\n### Code Quality\n\n```bash\n# Run ruff linting and formatting\nruff check respectify/\nruff format respectify/\n\n# Beartype provides runtime type checking automatically\n# No separate type checking step needed!\n```\n\n## Requirements\n\n- Python 3.9+\n- httpx >= 0.24.0\n- pydantic >= 2.0.0 \n- beartype >= 0.15.0\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Documentation**: [Full API documentation](https://docs.respectify.org)\n- **Issues**: [GitHub Issues](https://github.com/respectify/respectify-python/issues)\n- **Website**: [Respectify.ai](https://respectify.ai)\n\n## Changelog\n\n### v0.1.0 (2025-01-XX)\n\n- Initial release\n- Synchronous and asynchronous client support\n- Complete API coverage for all Respectify endpoints\n- Comprehensive type safety with Pydantic schemas\n- Megacall support for efficient batch operations\n- Full test suite with real API integration\n- Sphinx documentation with examples",
"bugtrack_url": null,
"license": null,
"summary": "Python client library for the Respectify API",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://docs.respectify.org",
"Homepage": "https://respectify.ai",
"Issues": "https://github.com/respectify/respectify-python/issues",
"Repository": "https://github.com/respectify/respectify-python"
},
"split_keywords": [
"abuse-detection",
" api",
" civility",
" comment",
" content-filtering",
" discourse",
" discussion",
" dogwhistle",
" moderation",
" respectify",
" spam",
" toxicity"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "58329c281d26a5823c7eba8e3cbb83ec3829b601f4b74f9c779a1cecbc1557d4",
"md5": "aac9775f8885803b20cb18c0a8ce7dfd",
"sha256": "c6bffd132191c499f326462a2f404cd0b0e531e1eed909a3ed73c4a0116102d0"
},
"downloads": -1,
"filename": "respectify-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aac9775f8885803b20cb18c0a8ce7dfd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 12939,
"upload_time": "2025-09-14T10:00:23",
"upload_time_iso_8601": "2025-09-14T10:00:23.822384Z",
"url": "https://files.pythonhosted.org/packages/58/32/9c281d26a5823c7eba8e3cbb83ec3829b601f4b74f9c779a1cecbc1557d4/respectify-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "72724c2f406ed2afea536e5922af79b9a4b797e13812d311b162cb17877ae30b",
"md5": "52f18fccb47c80ba52777f52c4ba84cf",
"sha256": "9aa358c611fbb0760db3293d32e1a365c1285b8003753fb2b30ca6ce538ea86a"
},
"downloads": -1,
"filename": "respectify-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "52f18fccb47c80ba52777f52c4ba84cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22988,
"upload_time": "2025-09-14T10:00:25",
"upload_time_iso_8601": "2025-09-14T10:00:25.652817Z",
"url": "https://files.pythonhosted.org/packages/72/72/4c2f406ed2afea536e5922af79b9a4b797e13812d311b162cb17877ae30b/respectify-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 10:00:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "respectify",
"github_project": "respectify-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "respectify"
}
JSON
