Official Python client library for the Instaparser API
Project description
Instaparser Python Library
A Python client library for the Instaparser API, providing a simple and intuitive interface for parsing articles, generating summaries, and processing PDFs.
Installation
pip install instaparser
Quick Start
from instaparser import InstaparserClient
# Initialize the client with your API key
client = InstaparserClient(api_key="your-api-key")
# Parse an article from a URL
article = client.Article(url="https://example.com/article")
# Access article properties
print(article.title)
print(article.body) # HTML or text content
print(article.author)
print(article.words)
Features
- Article Parsing: Extract clean HTML, text, or markdown from web articles
- Summary Generation: Generate AI-powered summaries with key sentences
- PDF Processing: Parse PDFs from URLs or file uploads
- Error Handling: Comprehensive exception handling for API errors
- Type Hints: Full type annotations for better IDE support
Usage
Article Parsing
Parse articles from URLs or HTML content:
from instaparser import InstaparserClient
client = InstaparserClient(api_key="your-api-key")
# Parse from URL (HTML output)
article = client.Article(url="https://example.com/article")
print(article.html) # HTML content
print(article.body) # Same as html when output='html'
# Parse from URL (text output)
article = client.Article(url="https://example.com/article", output="text")
print(article.text) # Plain text content
print(article.body) # Same as text when output='text'
# Parse from URL (markdown output)
article = client.Article(url="https://example.com/article", output="markdown")
print(article.markdown) # Markdown content
print(article.body) # Same as markdown when output='markdown'
# Parse from HTML content
html_content = "<html><body><h1>Title</h1><p>Content</p></body></html>"
article = client.Article(url="https://example.com/article", content=html_content)
# Disable cache
article = client.Article(url="https://example.com/article", use_cache=False)
Article Properties
The Article object provides access to all parsed metadata:
article = client.Article(url="https://example.com/article")
# Basic properties
article.url # Canonical URL
article.title # Article title
article.site_name # Website name
article.author # Author name
article.date # Published date (UNIX timestamp)
article.description # Article description
article.thumbnail # Thumbnail image URL
article.words # Word count
article.is_rtl # Right-to-left language flag
# Content
article.body # HTML, text, or markdown (depending on output format)
article.html # HTML content (if output='html')
article.text # Plain text (if output='text')
article.markdown # Markdown content (if output='markdown')
# Media
article.images # List of images
article.videos # List of embedded videos
Summary Generation
Generate AI-powered summaries:
# Generate summary
summary = client.Summary(url="https://example.com/article")
print(summary.overview) # Concise summary
print(summary.key_sentences) # List of key sentences
# Stream summary with callback (for real-time updates)
def on_stream_line(line):
print(f"Streaming: {line}")
summary = client.Summary(
url="https://example.com/article",
stream_callback=on_stream_line
)
PDF Processing
Parse PDFs from URLs or files. The PDF class inherits from Article, so it has all the same properties:
# Parse PDF from URL
pdf = client.PDF(url="https://example.com/document.pdf")
# Parse PDF from file
with open('document.pdf', 'rb') as f:
pdf = client.PDF(file=f)
# Parse PDF with text output
pdf = client.PDF(url="https://example.com/document.pdf", output="text")
print(pdf.text)
print(pdf.body) # Same as text when output='text'
# Parse PDF with markdown output
pdf = client.PDF(url="https://example.com/document.pdf", output="markdown")
print(pdf.markdown)
print(pdf.body) # Same as markdown when output='markdown'
# Access all Article properties
print(pdf.title)
print(pdf.words)
print(pdf.images)
Error Handling
The SDK provides specific exception types for different error scenarios:
from instaparser import (
InstaparserClient,
InstaparserAuthenticationError,
InstaparserRateLimitError,
InstaparserValidationError,
InstaparserAPIError,
)
client = InstaparserClient(api_key="your-api-key")
try:
article = client.Article(url="https://example.com/article")
except InstaparserAuthenticationError:
print("Invalid API key")
except InstaparserRateLimitError:
print("Rate limit exceeded")
except InstaparserValidationError:
print("Invalid request parameters")
except InstaparserAPIError as e:
print(f"API error: {e} (status: {e.status_code})")
API Reference
InstaparserClient
Main client class for interacting with the Instaparser API.
__init__(api_key: str)
Initialize the client.
api_key: Your Instaparser API key
Article(url: str, content: Optional[str] = None, output: str = 'html', use_cache: bool = True) -> Article
Parse an article from a URL or HTML content.
url: URL of the article (required)content: Optional HTML content to parse instead of fetching from URLoutput: Output format -'html'(default),'text', or'markdown'use_cache: Whether to use cache (default:True)
Returns: Article object
Summary(url: str, content: Optional[str] = None, use_cache: bool = True, stream_callback: Optional[Callable[[str], None]] = None) -> Summary
Generate a summary of an article.
url: URL of the article (required)content: Optional HTML content to parse instead of fetching from URLuse_cache: Whether to use cache (default:True)stream_callback: Optional callback function called for each line of streaming response. If provided, enables streaming mode.
Returns: Summary object with key_sentences and overview attributes
PDF(url: Optional[str] = None, file: Optional[Union[BinaryIO, bytes]] = None, output: str = 'html', use_cache: bool = True) -> PDF
Parse a PDF from a URL or file.
url: URL of the PDF (required for GET request)file: PDF file to upload (required for POST request)output: Output format -'html'(default),'text', or'markdown'use_cache: Whether to use cache (default:True)
Returns: PDF object (inherits from Article)
Article
Represents a parsed article from Instaparser.
Properties
url: Canonical URLtitle: Article titlesite_name: Website nameauthor: Author namedate: Published date (UNIX timestamp)description: Article descriptionthumbnail: Thumbnail image URLwords: Word countis_rtl: Right-to-left language flagimages: List of imagesvideos: List of embedded videosbody: Article body (HTML, text, or markdown)html: HTML content (if output was 'html')text: Plain text content (if output was 'text')markdown: Markdown content (if output was 'markdown')
Represents a parsed PDF from Instaparser. Inherits from Article and has all the same properties. PDFs always have is_rtl=False and videos=[].
Summary
Represents a summary result from Instaparser.
Properties
key_sentences: List of key sentences extracted from the articleoverview: Concise summary of the article
License
MIT
Support
For support, email support@instaparser.com or visit https://instaparser.com.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
instaparser-1.0.1.tar.gz
(55.5 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file instaparser-1.0.1.tar.gz.
File metadata
- Download URL: instaparser-1.0.1.tar.gz
- Upload date:
- Size: 55.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8134354b2d6bb86282b47db9b9587838dab23ba8450553fc071a9a6aabd4c98d
|
|
| MD5 |
bee55082e04f7e5014d2c6a86ffa3d73
|
|
| BLAKE2b-256 |
aae837a524c17e009b343911f2adc6c74662b1ffbce7243bae464395bd7d98af
|
File details
Details for the file instaparser-1.0.1-py3-none-any.whl.
File metadata
- Download URL: instaparser-1.0.1-py3-none-any.whl
- Upload date:
- Size: 10.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b0e33bc97fd9a158313dd0f0b34455f28ab54955efa96133a5e42275e853f89e
|
|
| MD5 |
3415f69bd600761f8f7997cab52953e8
|
|
| BLAKE2b-256 |
112e0d100f8fb6f5fe42eef8c7ef97ec1dd1b25253faad71136a8adda0e544b9
|
