tessl/pypi-praw
Python Reddit API Wrapper - simple access to Reddit's API
—
Pending
content-discovery.mddocs/
Content Discovery
PRAW provides comprehensive content discovery capabilities including front page listings, subreddit discovery, user discovery, and domain-based content access. These features help you explore Reddit's vast content ecosystem and find relevant communities and users.
Capabilities
Front Page Listings
Access Reddit's front page content with various sorting and filtering options.
class Front:
def __init__(self, reddit): ...
def best(self, **kwargs):
"""
Get best posts from Reddit front page.
Parameters:
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
Best posts use Reddit's algorithm combining hot and top factors.
"""
def hot(self, **kwargs):
"""
Get hot posts from Reddit front page.
Parameters:
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def new(self, **kwargs):
"""
Get newest posts from Reddit front page.
Parameters:
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def top(self, time_filter: str = "all", **kwargs):
"""
Get top posts from Reddit front page.
Parameters:
- time_filter: Time period ("all", "day", "week", "month", "year")
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def controversial(self, time_filter: str = "all", **kwargs):
"""
Get controversial posts from Reddit front page.
Parameters:
- time_filter: Time period ("all", "day", "week", "month", "year")
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def rising(self, **kwargs):
"""
Get rising posts from Reddit front page.
Parameters:
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def gilded(self, **kwargs):
"""
Get gilded posts from Reddit front page.
Parameters:
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def random_rising(self, **kwargs):
"""
Get random rising posts from Reddit front page.
Parameters:
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""Subreddit Discovery
Discover subreddits through various browsing and search methods.
class Subreddits:
def __init__(self, reddit): ...
def default(self, **kwargs):
"""
Get default subreddits.
Parameters:
- limit: Number of subreddits (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Subreddit instances
Default subreddits are automatically subscribed to new accounts.
"""
def gold(self, **kwargs):
"""
Get Reddit Gold/Premium exclusive subreddits.
Parameters:
- limit: Number of subreddits (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Subreddit instances
Requires Reddit Premium subscription to access.
"""
def new(self, **kwargs):
"""
Get newly created subreddits.
Parameters:
- limit: Number of subreddits (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Subreddit instances
"""
def popular(self, **kwargs):
"""
Get popular subreddits.
Parameters:
- limit: Number of subreddits (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Subreddit instances
Popular subreddits based on activity and subscriber growth.
"""
def recommended(self, omit_subreddits: list = None, **kwargs):
"""
Get recommended subreddits for current user.
Parameters:
- omit_subreddits: List of subreddit names to exclude
- limit: Number of subreddits (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Subreddit instances
Personalized recommendations based on user activity.
Requires authentication.
"""
def search(
self,
query: str,
*,
sort: str = "relevance",
**kwargs
):
"""
Search for subreddits by name and description.
Parameters:
- query: Search query
- sort: Sort order ("relevance", "activity")
- limit: Number of results (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Subreddit instances
"""
def stream(self, **kwargs):
"""
Stream newly created subreddits.
Parameters:
- pause_after: Pause after this many requests
- skip_existing: Skip subreddits created before stream start
Yields:
Subreddit instances as they are created
"""User Discovery
Find and search for Reddit users across the platform.
class Redditors:
def __init__(self, reddit): ...
def new(self, **kwargs):
"""
Get newly created user accounts.
Parameters:
- limit: Number of users (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Redditor instances
"""
def popular(self, **kwargs):
"""
Get popular Reddit users.
Parameters:
- limit: Number of users (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Redditor instances
Popular users based on karma and activity.
"""
def search(self, query: str, **kwargs):
"""
Search for Reddit users by username.
Parameters:
- query: Search query (partial username)
- limit: Number of results (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Redditor instances
"""
def stream(self, **kwargs):
"""
Stream newly created user accounts.
Parameters:
- pause_after: Pause after this many requests
- skip_existing: Skip users created before stream start
Yields:
Redditor instances as accounts are created
"""Domain-Based Discovery
Access content from specific domains and websites.
class DomainListing:
"""Listings for content from specific domains."""
def __init__(self, reddit, domain: str): ...
def hot(self, **kwargs):
"""
Get hot posts from the domain.
Parameters:
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def new(self, **kwargs):
"""
Get newest posts from the domain.
Parameters:
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def top(self, time_filter: str = "all", **kwargs):
"""
Get top posts from the domain.
Parameters:
- time_filter: Time period ("all", "day", "week", "month", "year")
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def controversial(self, time_filter: str = "all", **kwargs):
"""
Get controversial posts from the domain.
Parameters:
- time_filter: Time period ("all", "day", "week", "month", "year")
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def rising(self, **kwargs):
"""
Get rising posts from the domain.
Parameters:
- limit: Number of posts (default: 25, max: 100)
- params: Additional query parameters
Returns:
ListingGenerator of Submission instances
"""
def domain(self, domain: str) -> DomainListing:
"""
Get DomainListing for specific domain.
Parameters:
- domain: Domain name (e.g., "github.com", "youtube.com")
Returns:
DomainListing instance for the domain
"""Random Content Discovery
Access random content and subreddits.
def random_subreddit(self, nsfw: bool = False):
"""
Get a random subreddit.
Parameters:
- nsfw: Include NSFW subreddits in selection
Returns:
Subreddit instance
Randomly selects from active subreddits on Reddit.
"""
def random(self):
"""
Get a random submission from r/random.
Returns:
Submission instance
Equivalent to visiting reddit.com/r/random
"""Content Information and Metadata
Get detailed information about Reddit content by URL or ID.
def info(
self,
fullnames: list = None,
subreddits: list = None,
url: str = None
):
"""
Fetch information about Reddit objects.
Parameters:
- fullnames: List of Reddit fullnames (e.g., ["t3_abc123", "t1_def456"])
- subreddits: List of subreddit names
- url: URL to get information about
Returns:
Generator yielding Reddit objects (Submission, Comment, etc.)
Can fetch up to 100 objects per request using fullnames.
URLs are resolved to their corresponding Reddit objects.
"""
def username_available(self, name: str) -> bool:
"""
Check if username is available for registration.
Parameters:
- name: Username to check
Returns:
True if username is available, False if taken
"""Listing Generators and Pagination
Efficient iteration over large result sets with automatic pagination.
class ListingGenerator:
"""Generator for paginated API results."""
def __init__(self, reddit, url: str, **kwargs): ...
def __iter__(self):
"""Iterate over all items, handling pagination automatically."""
def __next__(self):
"""Get next item in sequence."""
@property
def params(self) -> dict:
"""Query parameters for the listing."""
def reset(self):
"""Reset generator to beginning."""
# Usage with custom limits and parameters
listing = reddit.front.hot(limit=100)
for submission in listing:
print(f"{submission.title} - {submission.score}")
# Access specific pages
listing = reddit.subreddit("python").new(limit=25, params={"after": "t3_abc123"})Usage Examples
Front Page Exploration
import praw
reddit = praw.Reddit(...)
# Get best posts from front page
print("Best posts:")
for submission in reddit.front.best(limit=10):
print(f"{submission.title} - r/{submission.subreddit.display_name}")
print(f"Score: {submission.score}, Comments: {submission.num_comments}")
# Get controversial posts from this week
print("\nControversial this week:")
for submission in reddit.front.controversial("week", limit=5):
print(f"{submission.title} - {submission.upvote_ratio:.2f} ratio")
# Get rising posts
print("\nRising posts:")
for submission in reddit.front.rising(limit=5):
print(f"{submission.title} - {submission.created_utc}")Subreddit Discovery
# Search for programming-related subreddits
print("Programming subreddits:")
for subreddit in reddit.subreddits.search("programming", limit=10):
print(f"r/{subreddit.display_name} - {subreddit.subscribers} subscribers")
print(f"Description: {subreddit.public_description}")
# Get popular subreddits
print("\nPopular subreddits:")
for subreddit in reddit.subreddits.popular(limit=10):
print(f"r/{subreddit.display_name} - {subreddit.subscribers} subscribers")
# Get new subreddits
print("\nNew subreddits:")
for subreddit in reddit.subreddits.new(limit=5):
print(f"r/{subreddit.display_name} - Created: {subreddit.created_utc}")User Discovery
# Search for users
print("Users matching 'python':")
for user in reddit.redditors.search("python", limit=5):
print(f"u/{user.name} - {user.comment_karma} comment karma")
# Get popular users
print("\nPopular users:")
for user in reddit.redditors.popular(limit=5):
print(f"u/{user.name} - Total karma: {user.total_karma}")
# Get new users
print("\nNew users:")
for user in reddit.redditors.new(limit=5):
print(f"u/{user.name} - Created: {user.created_utc}")Domain-Based Content
# Get content from specific domains
github_domain = reddit.domain("github.com")
print("Hot GitHub posts:")
for submission in github_domain.hot(limit=10):
print(f"{submission.title}")
print(f"r/{submission.subreddit.display_name} - {submission.score} points")
# Get top YouTube videos this week
youtube_domain = reddit.domain("youtube.com")
for submission in youtube_domain.top("week", limit=5):
print(f"{submission.title} - {submission.url}")Random Content Exploration
# Get random subreddits
for i in range(5):
random_sub = reddit.random_subreddit()
print(f"Random: r/{random_sub.display_name}")
# Include NSFW subreddits
random_nsfw = reddit.random_subreddit(nsfw=True)
print(f"Random NSFW: r/{random_nsfw.display_name}")
# Get random submission
random_post = reddit.random()
print(f"Random post: {random_post.title}")Content Information Lookup
# Look up content by fullnames
fullnames = ["t3_abc123", "t1_def456"] # submission and comment IDs
for item in reddit.info(fullnames=fullnames):
if hasattr(item, 'title'): # It's a submission
print(f"Submission: {item.title}")
else: # It's a comment
print(f"Comment: {item.body[:50]}...")
# Look up content by URL
url_content = list(reddit.info(url="https://www.reddit.com/r/python/comments/abc123/"))
for item in url_content:
print(f"Found: {item.title}")
# Check username availability
available = reddit.username_available("test_username_123")
print(f"Username available: {available}")Streaming New Content
# Stream new subreddits
print("Monitoring new subreddits...")
for subreddit in reddit.subreddits.stream():
print(f"New subreddit: r/{subreddit.display_name}")
print(f"Description: {subreddit.public_description}")
# Add your processing logic here
# Stream new users
print("Monitoring new users...")
for user in reddit.redditors.stream():
print(f"New user: u/{user.name}")
# Add your processing logic hereAdvanced Listing Usage
# Custom pagination
all_posts = []
after = None
for page in range(3): # Get 3 pages
params = {"limit": 25}
if after:
params["after"] = after
page_posts = list(reddit.subreddit("python").hot(**params))
all_posts.extend(page_posts)
if page_posts:
after = page_posts[-1].fullname
else:
break
print(f"Collected {len(all_posts)} posts across {page+1} pages")
# Filter results during iteration
high_karma_posts = []
for submission in reddit.front.hot(limit=100):
if submission.score > 1000:
high_karma_posts.append(submission)
if len(high_karma_posts) >= 10:
break
print(f"Found {len(high_karma_posts)} high karma posts")Types
class Listing:
"""Generic listing container."""
def __init__(self, reddit, json_dict: dict): ...
after: str # Pagination cursor for next page
before: str # Pagination cursor for previous page
children: list # List of contained objects
class FlairListing:
"""Flair-specific listing container."""
class ModNoteListing:
"""Moderator note listing container."""
class ModeratorListing:
"""Moderator listing container."""Install with Tessl CLI
npx tessl i tessl/pypi-praw