Meta

• License: MIT License (MIT License Copyright (c) [2025] [Helmut Hoffer von Ankershoffen (helmuthva@googlemail.com)] Permi...)
• Author:Helmut Hoffer von Ankershoffen
• Tags act, api, brave, brave-api, brave-search, brave-search-api, brave-search-python-client, bravesearch, bravesearchapi, codecov, copier, cyclonedx, detect-secrets, devcontainer, docker, git-cliff, jupyter, marimo, mypy, nox, oe-python-template, pip-audit, pip-licenses, pre-commit, pydantic, pypi, pytest, python, readthedocs, ruff, sonarcloud, sonarqube, sphinx, streamlit, typer, uv, web-search, websearch
• Requires: Python <4.0, >=3.11
• Provides-Extra:examples

Classifiers

• Development Status
  • 2 - Pre-Alpha
• Framework
  • AsyncIO
  • Pydantic
  • Pytest
• Intended Audience
  • Developers
  • End Users/Desktop
• License
  • OSI Approved :: MIT License
• Natural Language
  • English
• Operating System
  • MacOS :: MacOS X
  • Microsoft :: Windows
  • POSIX :: Linux
• Programming Language
  • Python
  • Python :: 3
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
• Typing
  • Typed

🦁 Brave Search Python Client

[!TIP]📚Online documentation - 📖PDF Manual

[!NOTE]🧠 This project was scaffolded using the templateoe-python-template withcopier.

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

Use Cases:

1. Integrate into your Python code to help users find what they're looking for.
2. Add to your AI applications to give LLMs access to current web information.
3. Use the built-in CLI in shell scripts to get search results in JSON format.

Overview

Adding Brave Search Python Client to your project as a dependency is easy.

uvaddbrave-search-python-client# add dependency to your project

If you don't have uv installed followthese instructions.If you still prefer pip over the modern and fast package manageruv, you can install the library like this:

pipinstallbrave-search-python-client# add dependency to your project

Obtain your Brave Search API key bysigning up here - the free tier includes 2,000requests per month. For guidance on how to integrate the Brave Search Pythonclient into your code base check out the examples below and explore thereference documentation.If you just want to try out the client without having to write code you can usethe integrated CLI:

exportBRAVE_SEARCH_API_KEY=YOUR_API_KEY# replace YOUR_API_KEYuvxbrave-search-python-clientweb"hello world"# search for hello world

All advanced search options of Brave Search are supportedby the clientand in the CLI:

# Find all German content about AI added in the last 24 hoursuvxbrave-search-python-clientweb--country=DE--search-lang=de--units=metric--freshness=pdai

The CLI provides extensive help:

uvxbrave-search-python-client--help# all CLI commandsuvxbrave-search-python-clientweb--help# all options for web searchuvxbrave-search-python-clientimages--help# all options image searchuvxbrave-search-python-clientvideos--help# all options video searchuvxbrave-search-python-clientnews--help# all options news search

Operational Excellence

This project is designed with operational excellence in mind, using modernPython tooling and practices. It includes:

1. Various examples demonstrating usage: a.Simple Python scriptb.Streamlit web applicationdeployed onStreamlit Community Cloud c.JupyterandMarimonotebook
2. Complete reference documentationon Read the Docs
3. Transparent test coverageincluding unit and E2E tests (reported on Codecov)
4. Matrix tested withmultiple python versionsto ensure compatibility (powered byNox)
5. Compliant with modern linting and formatting standards (powered byRuff)
6. Up-to-date dependencies (monitored byRenovate andDependabot)
7. A-grade code qualityin security, maintainability, and reliability with low technical debt andcodesmell (verified by SonarQube)
8. Additional code security checks usingCodeQL
9. Security Policy
10. License compliant with the Open Source Initiative (OSI)
11. 1-liner for installation and execution of command line interface (CLI) viauv(x) orDocker
12. Setup for developing inside adevcontainerincluded (supports VSCode and GitHub Codespaces)

Usage Examples

Streamlit App

Try it out! -Show the code

Minimal Python Script:

"""Example script demonstrating the usage of the Brave Search Python Client.For web, image, video and news search."""importasyncioimportosfromdotenvimportload_dotenvfromrich.consoleimportConsolefrombrave_search_python_clientimport(BraveSearch,CountryCode,ImagesSearchRequest,LanguageCode,NewsSearchRequest,VideosSearchRequest,WebSearchRequest,)# Load .env file and get Brave Search API key from environmentload_dotenv()api_key=os.getenv("BRAVE_SEARCH_API_KEY")ifnotapi_key:msg="BRAVE_SEARCH_API_KEY not found in environment"raiseValueError(msg)asyncdefsearch()->None:"""Run various searches using the Brave Search Python Client (see https://brave-search-python-client.readthedocs.io/en/latest/lib_reference.html)."""# Initialize the Brave Search Python client, using the API key from the environmentbs=BraveSearch()# Perform a web searchresponse=awaitbs.web(WebSearchRequest(q="jupyter"))# Print results as JSON# Iterate over web hits and render links in markdownfor_resultinresponse.web.resultsifresponse.webelse[]:pass# Advanced search with parametersresponse=awaitbs.web(WebSearchRequest(q="python programming",country=CountryCode.DE,search_lang=LanguageCode.DE,),)for_resultinresponse.web.resultsifresponse.webelse[]:pass# Search and render imagesresponse=awaitbs.images(ImagesSearchRequest(q="cute cats"))for_imageinresponse.resultsor[]:pass# Search and render videosresponse=awaitbs.videos(VideosSearchRequest(q="singularity is close"))for_videoinresponse.resultsor[]:pass# Search and render newsresponse=awaitbs.news(NewsSearchRequest(q="AI"))for_iteminresponse.resultsor[]:pass# Run the async search function# Alternatively use await search() from an async functionasyncio.run(search())

Show script code -

Read the library reference documentationfor an explanation of available classes and methods.

Jupyter Notebook

Show notebook code

Command Line Interface (CLI)

Run withuvx

Add Brave Search API key to the environment

exportBRAVE_SEARCH_API_KEY=YOUR_API_KEY

Show available commands:

uvxbrave-search-python-client--help

Search the web for "hello world":

uvxbrave-search-python-clientweb"hello world"

Show options for web search

uvxbrave-search-python-clientweb--help

Search images:

uvxbrave-search-python-clientimages"hello world"

Show options for image search

uvxbrave-search-python-clientimages--help

Search videos:

uvxbrave-search-python-clientvideos"hello world"

Show options for videos search

uvxbrave-search-python-clientvideos--help

Search news:

uvxbrave-search-python-clientnews"hello world"

Show options for news search

uvxbrave-search-python-clientnews--help

Read the CLI reference documentationfor an explanation of all commands and options.

Run with Docker

Note: Replace YOUR_BRAVE_SEARCH_API_KEY with your API key in the followingexamples.

Show available commands:

dockerrunhelmuthva/brave-search-python-client--help

Search the web:

dockerrun--envBRAVE_SEARCH_API_KEY=YOUR_BRAVE_SEARCH_API_KEYhelmuthva/brave-search-python-clientweb"hello world"

Show options for web search

dockerrunhelmuthva/brave-search-python-clientweb--help

Search images:

dockerrun--envBRAVE_SEARCH_API_KEY=YOUR_BRAVE_SEARCH_API_KEYhelmuthva/brave-search-python-clientimages"hello world"

Show options for image search

dockerrunhelmuthva/brave-search-python-clientimages--help

Search videos:

dockerrun--envBRAVE_SEARCH_API_KEY=YOUR_BRAVE_SEARCH_API_KEYhelmuthva/brave-search-python-clientvideos"hello world"

Show options for video search

dockerrunhelmuthva/brave-search-python-clientvideos--help

Search news:

dockerrun--envBRAVE_SEARCH_API_KEY=YOUR_BRAVE_SEARCH_API_KEYhelmuthva/brave-search-python-clientnews"hello world"

Show options for news search

dockerrunhelmuthva/brave-search-python-clientnews--help

Or use docker compose

File .env is passed through

dockercomposeupdockercomposerunbrave-search-python-client--help

Further Reading

• Inspect oursecurity policy with detailed documentation of checks, tools and principles.
• Check out theCLI reference with detailed documentation of all CLI commands and options.
• Check out thelibrary reference with detailed documentation of public classes and functions.
• Check out theAPI reference with detailed documentation of all API operations and parameters.
• Ourrelease notes provide a complete log of recent improvements and changes.
• In case you want to help us improve 🦁 Brave Search Python Client: Thecontribution guidelines explain how to setup your development environment and create pull requests.
• We gratefully acknowledge theopen source projects that this project builds upon. Thank you to all these wonderful contributors!

Star History

Verified details

Maintainers

helmuthva

Unverified details

Project links

• Changelog
• Documentation
• Homepage
• Issues
• Source

• Download URL:brave_search_python_client-0.4.27.tar.gz
• Upload date: Apr 27, 2025
• Size: 124.4 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: uv/0.6.3

See more details on using hashes here.

• Download URL:brave_search_python_client-0.4.27-py3-none-any.whl
• Upload date: Apr 27, 2025
• Size: 128.8 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: uv/0.6.3

See more details on using hashes here.