Contributing¶

Thank you for considering contributing to Brave Search Python Client!

Setup¶

Create a fork and clone your fork using git clone URL_OF_YOUR_CLONE. Then change into the directory of your local Brave Search Python Client repository with cd brave-search-python-client.

If you are one of the committers of https://github.com/helmut-hoffer-von-ankershoffen/brave-search-python-client you can directly clone via git clone git@github.com:helmut-hoffer-von-ankershoffen/brave-search-python-client.git and cd brave-search-python-client.

Install or update development dependencies using

make install

Directory Layout¶

├── Makefile               # Central entrypoint for build, test, release and deploy
├── noxfile.py             # Noxfile for running tests in multiple python environments and other tasks
├── .pre-commit-config.yaml # Definition of hooks run on commits
├── .github/               # GitHub specific files
│   ├── workflows/         # GitHub Actions workflows
│   ├── prompts/           # Custom prompots for GitHub Copilot
│   └── copilot-instructions.md # Insructions for GitHub Copilot
├── .vscode/               # Recommended VSCode settings and extensions
├── .env                   # Environment variables, on .gitignore
├── .env.example           # Example environment variables
src/brave_search_python_client/  # Source code
├── __init__.py          # Package initialization
├── constants.py         # Constants used throughout the app
├── settings.py          # Settings loaded from environment and .env
├── models.py            # Models and data structures
├── service.py           # Service exposed for use as shared library
└── cli.py               # CLI enabling to interact with service from terminal
tests/brave_search_python_client/ # Tests
├── **/cli_tests.py      # Verifies the core and module specific CLI commands
└── fixtures/            # Fixtures and mock data
docs/                    # Documentation
├── partials/*.md        # Partials to compile README.md,  _main partial included in HTML and PDF documentation
├── ../README.md         # Compiled README.md shown on GitHub
├── source/*.rst         # reStructuredText files used to generate HTML and PDF documentation
├── ../*.md              # Markdown files shown on GitHub and imported by .rst files
├── source/conf.py       # Sphinx configuration used to generate HTML and PDF documentation
├── build/html/*         # Generated HTML documentation as multiple pages
├── build/singlehtml/index.html # HTML documentation as a single page
└── build/latex/brave-search-python-client.pdf # PDF manual - generate with make docs pdf
examples/                # Example code demonstrating use of the project
├── streamlit.py         # Streamlit App, deployed in Streamlit Community Cloud
├── notebook.py          # Marimo notebook
├── notebook.ipynb       # Jupyter notebook
└── script.py            # Minimal script
reports/                 # Compliance reports for auditing
├── junit.xml            # Report of test executions run with pytest
├── mypy_junit.xml       # Report of static typing validation run with mypy
├── coverage.xml         # Test coverage in XML format generated by pytest-cov
├── coverage_html        # Report of test coverage in HTML format
├── licenses.csv         # List of dependencies and their license types
├── licenses.json        # .json file with dependencies their license types
├── licenses_grouped.json  # .json file with dependencies grouped by license type
├── vulnerabilities.json # .json file with vulnerabilities detected in dependencies by pip-audit
└── sbom.json            # Software Bill of Materials in OWASP CycloneDX format

Build, Run and Release¶

Setup project specific development environment¶

make setup

Don’t forget to configure your .env file with the required environment variables.

Notes:

.env.example is provided as a template, use cp .env.example .env and edit .env to create your environment.
.env is excluded from version control, so feel free to add secret values.

Build¶

make        # Runs primary build steps, i.e. formatting, linting, testing, building HTML docs and distribution, auditing
make help   # Shows help with additional build targets, e.g. to build PDF documentation, bump the version to release etc.

Notes:

Primary build steps defined in noxfile.py.
Distribution dumped into dist/
Documentation dumped into docs/build/html/ and docs/build/latex/
Audit reports dumped into reports/

Run the CLI¶

uv run brave-search-python-client # shows help

Commit and Push your changes¶

git add .
git commit -m "feat(user): added new api endpoint to offboard user"
git push

Notes:

pre-commit hooks will run automatically on commit to ensure code quality.
We use the conventional commits format - see the code style guide for the mandatory commit message format.

Publish Release¶

make bump   # Patch release
make minor  # Patch release
make major  # Patch release
make x.y.z  # Targeted release

Notes:

Changelog generated automatically
Publishes to PyPi, Docker Registries, Read The Docs, Streamlit and Auditing services

Advanced usage¶

Example: Streamlit Example App¶

uv sync --all-extras # required streamlit dependency part of the examples extra, see pyproject.toml
streamlit run examples/streamlit.py

Example: Jupyter Notebook¶

uv sync --all-extras # required streamlit dependency part of the examples extra, see pyproject.toml

Install the Jupyter extension for VSCode

Click on examples/notebook.ipynb in VSCode and run it

Running GitHub CI Workflow locally¶

make act

Notes:

Workflow defined in .github/workflows/*.yml
ci-cd.yml calls all build steps defined in noxfile.py

Docker¶

Build and run the Docker image with plain Docker

# Build from Dockerimage
make docker_build # builds targets all and slim

# Run the CLI
docker run --env THE_VAR=THE_VALUE -t brave-search-python-client --target all --help    # target with all extras
docker run --env THE_VAR=THE_VALUE -t brave-search-python-client --target slim --help   # slim flavor, no extras

Build and run the Docker image with docker compose:

echo "Building the Docker image with docker compose and running CLI..."
docker compose run --build brave-search-python-client --help
echo "Building the Docker image with docker compose and running API container as a daemon ..."
docker compose up --build -d
echo "Waiting for the notebook server to start..."
echo "Shutting down the notebook container ..."
docker compose down

Pinning GitHub Actions¶

pinact run  # See https://dev.to/suzukishunsuke/pin-github-actions-to-a-full-length-commit-sha-for-security-2n7p

Update from Template¶

Update project to latest version of oe-python-template template.

make update_from_template

Pull Request Guidelines¶

Before starting to write code read the code style document for mandatory coding style requirements.
Pre-Commit Hooks: We use pre-commit hooks to ensure code quality. Please install the pre-commit hooks by running uv run pre-commit install. This ensure all tests, linting etc. pass locally before you can commit.
Squash Commits: Before submitting a pull request, please squash your commits into a single commit.
Signed Commits: Use signed commits.
Branch Naming: Use descriptive branch names like feature/your-feature or fix/issue-number.
Testing: Ensure new features have appropriate test coverage.
Documentation: Update documentation to reflect any changes or new features.