tessl/pypi-ddgs

A metasearch library that aggregates results from diverse web search services

—

Pending

Overview

Eval results

Files

Core Search Methods

Name: tessl/pypi-ddgs
Author: tessl

Fundamental search functionality across five major categories: text, images, news, videos, and books. Each method supports region-specific searches, safety filters, time-limited results, and backend selection with automatic fallback and result aggregation.

Capabilities

Text Search

Performs text search across multiple search engines including Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex, and Wikipedia with automatic result ranking and deduplication.

def text(
    query: str,
    *,
    region: str = "us-en",
    safesearch: str = "moderate", 
    timelimit: str | None = None,
    max_results: int | None = 10,
    page: int = 1,
    backend: str = "auto",
    **kwargs: Any
) -> list[dict[str, Any]]:
    """
    Perform text search across multiple search engines.
    
    Parameters:
    - query: Search query string (required)
    - region: Search region in format "country-language" (default: "us-en")
    - safesearch: Safety level "on"/"moderate"/"off" (default: "moderate")
    - timelimit: Time filter "d"/"w"/"m"/"y" for day/week/month/year (default: None)
    - max_results: Maximum number of results to return (default: 10)
    - page: Page number for pagination (default: 1)
    - backend: Search backend selection (default: "auto")
    
    Available backends:
    - "auto": Automatic backend selection with Wikipedia prioritized first
    - "all": All available backends with Wikipedia prioritized first
    - "wikipedia": Wikipedia search engine
    - "bing": Bing search engine  
    - "brave": Brave search engine
    - "duckduckgo": DuckDuckGo search engine (currently disabled due to rate limits)
    - "google": Google search engine
    - "mojeek": Mojeek search engine
    - "mullvad_brave": Mullvad Leta via Brave
    - "mullvad_google": Mullvad Leta via Google
    - "yandex": Yandex search engine
    - "yahoo": Yahoo search engine
    
    Returns:
    List of dictionaries with keys:
    - title: str - Result title
    - href: str - Result URL
    - body: str - Result description/snippet
    """

Usage Example:

with DDGS() as ddgs:
    # Basic text search
    results = ddgs.text("python programming")
    
    # Advanced text search with filters
    results = ddgs.text(
        "machine learning tutorials",
        region="us-en",
        safesearch="moderate",
        timelimit="w",  # last week
        max_results=20,
        backend="google,bing"  # specific backends
    )
    
    for result in results:
        print(f"Title: {result['title']}")
        print(f"URL: {result['href']}")  
        print(f"Description: {result['body']}")
        print("-" * 50)

Image Search

Performs image search with support for size, color, type, layout, and license filtering.

def images(
    query: str,
    *,
    region: str = "us-en",
    safesearch: str = "moderate",
    timelimit: str | None = None, 
    max_results: int | None = 10,
    page: int = 1,
    backend: str = "auto",
    size: str | None = None,
    color: str | None = None,
    type_image: str | None = None,
    layout: str | None = None,
    license_image: str | None = None,
    **kwargs: Any
) -> list[dict[str, Any]]:
    """
    Perform image search with filtering options.
    
    Parameters:
    - query: Search query string (required)
    - size: Image size "Small"/"Medium"/"Large"/"Wallpaper"
    - color: Color filter "color"/"Monochrome"/"Red"/"Orange"/"Yellow"/"Green"/"Blue"/"Purple"/"Pink"/"Brown"/"Black"/"Gray"/"Teal"/"White"
    - type_image: Image type "photo"/"clipart"/"gif"/"transparent"/"line"
    - layout: Layout preference "Square"/"Tall"/"Wide"
    - license_image: License type "any"/"Public"/"Share"/"ShareCommercially"/"Modify"/"ModifyCommercially"
    
    Available backends: "auto", "all", "duckduckgo"
    
    Returns:
    List of dictionaries with keys:
    - title: str - Image title
    - image: str - Full-size image URL
    - thumbnail: str - Thumbnail image URL  
    - url: str - Source page URL
    - height: str - Image height in pixels
    - width: str - Image width in pixels
    - source: str - Image source/domain
    """

News Search

Performs news search across news sources with date filtering and source information.

def news(
    query: str,
    *,
    region: str = "us-en",
    safesearch: str = "moderate",
    timelimit: str | None = None,
    max_results: int | None = 10, 
    page: int = 1,
    backend: str = "auto",
    **kwargs: Any
) -> list[dict[str, Any]]:
    """
    Perform news search across news sources.
    
    Available backends: "auto", "all", "duckduckgo", "yahoo"
    
    Returns:
    List of dictionaries with keys:
    - date: str - Publication date
    - title: str - Article title
    - body: str - Article summary/content
    - url: str - Article URL
    - image: str - Article image URL (if available)
    - source: str - News source name
    """

Video Search

Performs video search with resolution, duration, and license filtering.

def videos(
    query: str,
    *,
    region: str = "us-en", 
    safesearch: str = "moderate",
    timelimit: str | None = None,
    max_results: int | None = 10,
    page: int = 1,
    backend: str = "auto",
    resolution: str | None = None,
    duration: str | None = None,
    license_videos: str | None = None,
    **kwargs: Any
) -> list[dict[str, Any]]:
    """
    Perform video search with filtering options.
    
    Parameters:
    - resolution: Video quality "high"/"standard"
    - duration: Video length "short"/"medium"/"long"  
    - license_videos: License type "creativeCommon"/"youtube"
    
    Available backends: "auto", "all", "duckduckgo"
    
    Returns:
    List of dictionaries with keys:
    - title: str - Video title
    - content: str - Video content description
    - description: str - Video description
    - duration: str - Video duration
    - embed_html: str - HTML embed code
    - embed_url: str - Embeddable video URL
    - image_token: str - Image token identifier
    - images: dict[str, str] - Video thumbnail images
    - provider: str - Video provider (YouTube, Vimeo, etc.)
    - published: str - Publication date
    - publisher: str - Publisher name
    - statistics: dict[str, str] - View counts and other stats
    - uploader: str - Video uploader name
    """

Book Search

Performs book search across book databases and archives.

def books(
    query: str,
    *,
    max_results: int | None = 10,
    page: int = 1,
    backend: str = "auto",
    **kwargs: Any
) -> list[dict[str, Any]]:
    """
    Perform book search across book databases.
    
    Note: Books search does not support region, safesearch, or timelimit filters.
    
    Available backends: "auto", "all", "annasarchive"
    
    Returns:
    List of dictionaries with keys:
    - title: str - Book title
    - author: str - Book author(s)
    - publisher: str - Publisher name
    - info: str - Book information/description
    - url: str - Book page URL
    - thumbnail: str - Book cover thumbnail URL
    """

Common Parameters

All search methods accept these standard parameters:

query (str, required): The search query string
region (str): Search region in format "country-language" (default: "us-en")
safesearch (str): Content filtering level "on"/"moderate"/"off" (default: "moderate")
timelimit (str | None): Time-based filtering "d"/"w"/"m"/"y" (default: None)
max_results (int | None): Maximum results to return (default: 10)
page (int): Page number for pagination (default: 1)
backend (str): Backend selection "auto"/"all" or specific engine names (default: "auto")

Backend Selection

You can specify multiple backends using comma-separated values:

# Use specific engines
results = ddgs.text("query", backend="google,bing,brave")

# Use all available engines  
results = ddgs.text("query", backend="all")

# Use automatic selection (recommended)
results = ddgs.text("query", backend="auto")  # or omit parameter

Error Handling

All search methods may raise:

DDGSException: General API errors
RatelimitException: When rate limits are exceeded
TimeoutException: When requests timeout

from ddgs import DDGS, DDGSException, TimeoutException

try:
    with DDGS(timeout=10) as ddgs:
        results = ddgs.text("search query")
except TimeoutException:
    print("Search timed out")
except DDGSException as e:
    print(f"Search error: {e}")

Install with Tessl CLI