brave-search-python-client 0.0.9

🦁 Brave Search Python Client supporting Web, Image, News and Video search.

[PRE-ALPHA] 🦁 Brave Search Python Client

⚠️ WARNING: This project is currently in pre-alpha phase, i.e. partly functional. Feel free to already watch or star the repository to stay updated on its progress.

Overview

Brave Search Python Client supporting Web, Image, News and Video search.

• Modern async Python client for Web, Image, Video and News search powered by Brave Search
• Thorough validation of both requests and responses (powered by Pydantic)
• 100% test coverage including unit and E2E tests (reported on Codecov)
• 100% compliance modern linting and formatting standards (powered by Ruff)
• 100% up-to-date dependencies (monitored by Renovate)
• A-grade code quality in security, maintainability, and reliability (verified by SonarQube)
• 1-liner for installation and execution of command line interface (CLI) via uv(x) or Docker
• Setup for developing inside a devcontainer included (supports VSCode and GitHub Codespaces)
• Various Examples: on Streamlit Community Cloud
  • Jupyter Notebook
  • Simple Python Script
• Later: MCP server to connect Brave Search with Claude Desktop and other MCP clients

Example Use

Streamlit App

Streamlit App deployed on Streamlit Community Cloud

TK (Screencast)

Jupyter Notebook

Show more

Minimal Python Script:

import asyncio
import json
import os

from dotenv import load_dotenv

from brave_search_python_client import (
    BraveSearch,
    CountryCode,
    ImagesSearchRequest,
    LanguageCode,
    NewsSearchRequest,
    VideosSearchRequest,
    WebSearchRequest,
)

# Load .env file and check for Brave Search API Key
load_dotenv()
api_key = os.getenv("BRAVE_SEARCH_API_KEY")
if not api_key:
    raise Exception("BRAVE_SEARCH_API_KEY found in environment")


async def search():
    """Run various searches using the Brave Search Python Client"""

    # Initialize the BraveSearch client, using the API key from the environment
    bs = BraveSearch()

    # Perform a web search
    response = await bs.web(WebSearchRequest(q="jupyter"))

    # Print results as JSON
    print("# Web search")
    print("## JSON response")
    print(json.dumps(response.model_dump(), indent=2))

    # Iterate over web hits and render links in markdown
    print("## Iterate and render")
    for result in response.web.results if response.web else []:
        print(f"[{result.title}]({result.url})")

    # Advanced search with parameters
    response = await bs.web(
        WebSearchRequest(
            q="python programming",
            country=CountryCode.DE,
            search_lang=LanguageCode.DE,
        )
    )

    print("# Advanced search results")
    for result in response.web.results if response.web else []:
        print(f"[{result.title}]({result.url})")

    # Search and render images
    print("# Images")
    response = await bs.images(ImagesSearchRequest(q="cute cats"))
    for image in response.results if response.results else []:
        print(f"![{image.source}]({image.url})")

    # Search and render videos
    print("# Videos")
    response = await bs.videos(VideosSearchRequest(q="singularity is close"))
    for video in response.results if response.results else []:
        print(f"![{video.title}]({video.url})")

    # Search and render news
    print("# News")
    response = await bs.news(NewsSearchRequest(q="AI"))
    for item in response.results if response.results else []:
        print(f"![{item.title}]({item.url})")


# Execute the search function
# Alternatively use await(search()) in an async function
asyncio.run(search())

Command Line Interface (CLI)

Run with uvx

Create .env file with API key:

./setup--dot-env YOUR_BRAVE_SEARCH_API_KEY

Show available commands:

uvx brave-search-python-client --help

Search the web for "hello world":

uvx brave-search-python-client web "hello world"

Show options for web search

uvx brave-search-python-client web --help

Search images:

uvx brave-search-python-client images "hello world"

Show options for image search

uvx brave-search-python-client images --help

Search videos:

uvx brave-search-python-client videos "hello world"

Show options for videos search

uvx brave-search-python-client videos --help

Search news:

uvx brave-search-python-client news "hello world"

Show options for news search

uvx brave-search-python-client news --help

Run with Docker

Show options for news search

docker run helmuthva/brave-search-python-client news --help

Docker

Note: Replace YOUR_BRAVE_SEARCH_API_KEY with your API key in the following examples.

Show available commands:

docker run helmuthva/brave-search-python-client --help

Search the web:

docker run --env BRAVE_SEARCH_API_KEY=YOUR_BRAVE_SEARCH_API_KEY helmuthva/brave-search-python-client web "hello world"

Show options for web search

docker run helmuthva/brave-search-python-client web --help

Search images:

docker run --env BRAVE_SEARCH_API_KEY=YOUR_BRAVE_SEARCH_API_KEY helmuthva/brave-search-python-client images "hello world"

Show options for image search

docker run helmuthva/brave-search-python-client images --help

Search videos:

docker run --env BRAVE_SEARCH_API_KEY=YOUR_BRAVE_SEARCH_API_KEY helmuthva/brave-search-python-client videos "hello world"

Show options for video search

docker run helmuthva/brave-search-python-client videos --help

Search news:

docker run --env BRAVE_SEARCH_API_KEY=YOUR_BRAVE_SEARCH_API_KEY helmuthva/brave-search-python-client news "hello world"

Show options for news search

docker run helmuthva/brave-search-python-client news --help

Extra: MCP Server

TK

Contributing

Please read our Contributing Guidelines for how to setup your development environment, and guidance for making pull requests.

Resources

• API
• MCP Specification and SDKs

Star History