feat(example): streamlit app

Author: helmut-hoffer-von-ankershoffen

CONTRIBUTING.md

@@ -25,11 +25,6 @@ uv run pre-commit install             # install pre-commit hooks, see https://pr
 
 ### Linux
 
-Notes:
-
-- Not yet validated
-- .github/workflows/test-and-report.yml might provide further information
-
 ```shell
 sudo sudo apt install -y curl jq libxml2-utils gnupg2  # tooling
 curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash # act
@@ -46,11 +41,28 @@ src/brave_search_python_client/
 ├── constants.py         # Constants
 ├── requests.py          # Pydantic models for requests
 └── responses/           # Pydantic models for responses
-tests/
+tests/                   # Unit and E2E tests
 ├── client_test.py       # Client tests including response validation
 ├── requests_tests.py    # Tests for request validation
 ├── cli_test.py          # CLI tests
 └── fixtures/            # Example responses
+examples/                # Example code demonstrating use of hte client
+├── streamlit.py         # Streamlit App
+```
+
+## Run
+
+### CLI
+
+```bash
+uv run brave-search-python-client --help
+```
+
+### Extra: Streamlit Example App
+
+```bash
+uv sync --all-extras # streamlit is an extra of this package
+sreamlit run examples/streamlit.py
 ```
 
 ## Build
@@ -69,18 +81,18 @@ uv run nox -s lint      # run formatting and linting
 uv run nox -s audit     # run security and license audit, inc. sbom generation
 ```
 
-## Running GitHub CI workflow locally
-
-Notes:
-
-- Workflow defined in .github/workflows/ci.yml
-- Calls all build steps defined in noxfile.py
+### Running GitHub CI workflow locally
 
 ```shell
 ./github-action-run.sh
 ```
 
-## Docker
+Notes:
+
+- Workflow defined in .github/workflows/*.yml
+- test-and-report.yml calls all build steps defined in noxfile.py
+
+### Docker
 
 ```shell
 docker build -t brave-search-python-client .

examples/streamlit.py

@@ -0,0 +1,64 @@
+import asyncio
+
+import streamlit as st
+
+from brave_search_python_client import (
+    BraveSearch,
+    WebSearchApiResponse,
+    WebSearchRequest,
+    __version__,
+)
+
+sidebar = st.sidebar
+api_key = api_key = sidebar.text_input(
+    "[Brave Search API key](https://brave.com/search/api/)"
+)
+sidebar.write(
+    f" [Brave Search Python Client v{__version__}](https://helmuthva.gitbook.io/brave-search-python-client)"
+)
+sidebar.write("Built with love in Berlin 🐻")
+
+st.title("🦁 Brave Search ")
+q = st.text_input("Query")
+
+if api_key and q:
+    # Initialize the BraveSearch client
+    bs = BraveSearch(api_key=api_key)
+
+    @st.cache_data
+    def search(q: str) -> WebSearchApiResponse:
+        """
+        Performs a synchronous web search using Brave Search API.
+
+        This function wraps an asynchronous API call into a synchronous interface by using
+        asyncio.run(). It executes a web search query through the Brave Search API.
+
+        Args:
+            q (str): The search query string to be sent to Brave Search
+
+        Returns:
+            WebSearchApiResponse: The response object from Brave Search API containing search results
+
+        Example:
+            >>> response = search("python programming")
+            >>> print(response.web.results[0].title)
+        """
+        return asyncio.run(bs.web(WebSearchRequest(q=q)))
+
+    # Perform the search
+    response = search(q)
+
+    # Print the response as JSON
+    cols = st.columns([0.1, 0.9])
+    with cols[0]:
+        st.write("JSON:")
+    with cols[1]:
+        st.json(response.model_dump(), expanded=False)
+
+    # Print the search results of type web
+    for result in response.web.results if response.web else []:
+        st.write(f"[{result.title}]({result.url})")
+elif q:
+    st.write(
+        "Please enter your [Brave Search API key](https://brave.com/search/api/) in the sidebar."
+    )

pyproject.toml

@@ -2,6 +2,7 @@
 name = "brave-search-python-client"
 version = "0.0.6"
 description = "🦁 Brave Search Python Client supporting Web, Image, News and Video search."
+readme = "README.md"
 authors = [
     { name = "Helmut Hoffer von Ankershoffen", email = "helmuthva@googlemail.com" },
 ]
@@ -23,6 +24,7 @@ keywords = [
     "typer",
     "uv",
 ]
+
 classifiers = [
     "Development Status :: 2 - Pre-Alpha",
     "Intended Audience :: Developers",
@@ -90,6 +92,8 @@ dev = [
 
 
 [project.optional-dependencies]
+streamlit = ["streamlit>=1.41.1"]
+
 # used by uv pip install -e ".[dev]", as used within nox (uv run nox)
 dev = [
     "bump-my-version>=0.29.0",

sonar-project.properties

@@ -8,4 +8,5 @@ sonar.links.ci=https://github.com/helmut-hoffer-von-ankershoffen/brave-search-py
 sonar.links.issues=https://github.com/helmut-hoffer-von-ankershoffen/brave-search-python-client/issues
 sonar.python.coverage.reportPaths=coverage.xml
 sonar.python.version=3.11, 3.12, 3.13
-sonar.coverage.exclusions=noxfile.py, tests/**
+sonar.coverage.exclusions=noxfile.py, tests/**, examples/**
+sonar.exclusions=examples/**