Skip to main content

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

Project description

🦁 Brave Search Python Client

License PyPI - Python Version CI Read the Docs Quality Gate Security Maintainability Technical Debt Code Smells Coverage Ruff GitHub - Version GitHub - Commits PyPI - Version PyPI - Status Docker - Version Docker - Size

Overview

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

Setup

Installation is as simple as:

uv add brave_search_python_client

If you still prefer pip over uv:

pip install brave_search_python_client

Highlights

Usage Examples

Streamlit App

Watch it

Try it out! - 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 get Brave Search API key from environment
load_dotenv()
api_key = os.getenv("BRAVE_SEARCH_API_KEY")
if not api_key:
    raise Exception("BRAVE_SEARCH_API_KEY not found in environment")


async def search():
    """Run various searches using the Brave Search Python Client (see https://brave-search-python-client.readthedocs.io/en/latest/reference_index.html)"""

    # Initialize the Brave Search Python 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})")


# Run the async search function
# Alternatively use await search() from an async function
asyncio.run(search())

Show script code - Read the reference documentation

Jupyter Notebook

Jupyter Notebook

Show notebook 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

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

Star History

Star History Chart

Project details


Release history Release notifications | RSS feed

This version

0.2.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

brave_search_python_client-0.2.1.tar.gz (36.8 MB view details)

Uploaded Source

Built Distribution

brave_search_python_client-0.2.1-py3-none-any.whl (65.1 kB view details)

Uploaded Python 3

File details

Details for the file brave_search_python_client-0.2.1.tar.gz.

File metadata

File hashes

Hashes for brave_search_python_client-0.2.1.tar.gz
Algorithm Hash digest
SHA256 d54d6f30520ff01e886a9a9d571ccf3e2b80bf181e31098a2fa47666299da3d3
MD5 980f13d3554a4642e0e62460d434f021
BLAKE2b-256 8e807a7e7173ca19f385543e9036166d645e057fe897bb664f38cc1a0db88b3b

See more details on using hashes here.

File details

Details for the file brave_search_python_client-0.2.1-py3-none-any.whl.

File metadata

File hashes

Hashes for brave_search_python_client-0.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ccf4508e5225937a06e47a5e549fe5920b32624cf4157645409ac73b60e091fe
MD5 4be815500e27351073d962d97de87e24
BLAKE2b-256 d22a47cc87961520ba2806435867c96e4485b769182ef0bdf72c2a9f1328d90e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page