🦁 Brave Search Python Client

GitHub - Commits

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
Various Examples:
- Streamlit App deployed on Streamlit Community Cloud
- Jupyter Notebook
- Simple Python Script
Thorough validation of both requests and responses (powered by Pydantic)
100% test coverage including unit and E2E tests (reported on Codecov)
100% compliance with 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)
Later: MCP server to connect Brave Search with Claude Desktop and other MCP clients

Usage

Streamlit App

Watch it

Try it out! - Show the code

Jupyter Notebook

Show the code

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())

Show the code

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

Contributing

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

Resources

Star History

Metadata

Release files for brave-search-python-client 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for brave-search-python-client 0.1.2
File	Size	Uploaded
brave_search_python_client-0.1.2.tar.gz	36.7 MB	Jan 1, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for brave-search-python-client 0.1.2
File	Interpreter	ABI	Platform	Reset
brave_search_python_client-0.1.2-py3-none-any.whl 64.9 kB Jan 1, 2025	Python 3	none	any	Details

Total release size: 36.7 MB

Release files / brave_search_python_client-0.1.2.tar.gz

Download URL	brave_search_python_client-0.1.2.tar.gz
Size	36.7 MB
Tags	Source
SHA-256 checksum How to use checksums	`fe23200dd59d8bd5e566fb20712769a43463186c360fe6c239c6d4459e3c4f13`
BLAKE2b-256 checksum How to use checksums	`aec5c23dc32e915ffb41fea223544890ab9189f80d2f9c65f73fbdabcd73c40d`
Upload date	Jan 1, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.5.9`

Release files / brave_search_python_client-0.1.2-py3-none-any.whl

Download URL	brave_search_python_client-0.1.2-py3-none-any.whl
Size	64.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`08cb358d15aa6976b9c00ceb8ca21521030635f1132c8af07b694145605add78`
BLAKE2b-256 checksum How to use checksums	`a3b8f9fd3d55f5b621b30cf802b82df35bd1f7e080b5764152d6b02db00fe7c0`
Upload date	Jan 1, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.5.9`