pyproject.toml

[project]
name = "brave-search-python-client"
version = "0.2.22"
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" },
]
license = { file = "LICENSE" }

keywords = [
    "api",
    "async",
    "brave",
    "brave-api",
    "bravesearch",
    "brave-search",
    "bravesearchapi",
    "codecov",
    "docker",
    "pydantic",
    "python",
    "ruff",
    "search",
    "sonarqube",
    "typer",
    "uv",
]

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

requires-python = ">=3.11,<4.0"

dependencies = [
    "httpx >= 0.28.1",
    "pydantic >= 2.5.2",
    "python-dotenv>=1.0.1",
    "streamlit>=1.41.1",
    "tenacity >= 9.0.0",
    "typer>=0.15.1",
]

[project.scripts]
brave-search-python-client = "brave_search_python_client.cli:cli"

[project.urls]
Homepage = "https://brave-search-python-client.readthedocs.io/"
Documentation = "https://brave-search-python-client.readthedocs.io/"
Source = "https://github.com/helmut-hoffer-von-ankershoffen/brave-search-python-client"
Changelog = "https://github.com/helmut-hoffer-von-ankershoffen/brave-search-python-client/releases"
Issues = "https://github.com/helmut-hoffer-von-ankershoffen/brave-search-python-client/issues"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project.optional-dependencies]
examples = ["jupyter>=1.1.1"]

[dependency-groups]
dev = [
    "autodoc-pydantic>=2.2.0",
    "bump-my-version>=0.29.0",
    "cyclonedx-py>=1.0.1",
    "detect-secrets>=1.5.0",
    "enum-tools>=0.12.0",
    "furo>=2024.8.6",
    "git-cliff>=2.7.0",
    "nox[uv]>=2024.10.9",
    "pip-audit>=2.7.3",
    "pip-licenses>=5.0.0",
    "pre-commit>=4.0.1",
    "pyright>=1.1.391",
    "pytest>=8.3.4",
    "pytest-asyncio>=0.25.1",
    "pytest-cov>=6.0.0",
    "pytest-docker>=3.1.1",
    "pytest-env>=1.1.5",
    "pytest-xdist[psutil]>=3.6.1",
    "ruff>=0.8.6",
    "sphinx>=8.1.3",
    "sphinx-autobuild>=2024.10.3",
    "sphinx-copybutton>=0.5.2",
    "sphinx-inline-tabs>=2023.4.21",
    "sphinx-mdinclude>=0.6.2",
    "sphinxext.opengraph>=0.9.1",
    "sphinx-pydantic>=0.1.1",
    "sphinx-rtd-theme>=3.0.2",
    "sphinx-toolbox>=3.8.1",
    "sphinxext-opengraph>=0.9.1",
    "tomli>=2.1.0",
    "matplotlib>=3.10.0",
    "pytest-regressions>=2.6.0",
]

[tool.ruff]
target-version = "py311"
preview = true
fix = true
line-length = 120
exclude = [".fixme"]


[tool.ruff.lint]
select = ["ALL"]

ignore = [
    "ANN002",   # missing type annotation for `*args` -> provides no value
    "ANN003",   # missing type annotation for `**kwargs`` -> provides no value
    "ASYNC109", # async function definition with a `timeout` parameter  -> as mentioned by ruff, "This rule is highly opinionated and may not be suitable for all use cases."
    "CPY001",   # missing copyright notice -> not for OSS
    "DOC502",   # docstrings with exceptions not raised in the code of the function -> not always necessary
    "D203",     # incomptatible with D211 -> prefer D211
    "D212",     # incompatible with D213 -> prefer D213
    "FBT001",   # boolean positional arguments -> disagree
    "FBT002",   # boolean defautl value positionl arguments -> disagree
    "FBT003",   # boolean positional value in function call -> disagree
    "PGH003",   # use specific rule codes when ignoring type issues -> quite a hassle, no value
    "TRY300",   # else instead of return before except. -> strongly disagree, hinders readabilty.
    "COM812",   # conflicts with ruff formatter -> not feasible nor recommended
    "ISC001",   # conflicts with ruff formatter -> not feasible nor recommended
    "S404",     # subprocess` module is possibly insecure -> as mentioned by ruff, unstable and preview
    "FIX002",   # line contains todo -> yes, that's what todo's are for?!
    "TD003",    # missing issue link for todo -> not in OSS
]

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = [
    # we are more relaxed in tests, while sill applying hundreds of rules
    "S101",     # asserts allowed in tests...
    "ARG",      # unused function args -> fixtures nevertheless are functionally relevant...
    "FBT",      # don't care about booleans as positional arguments in tests, e.g. via @pytest.mark.parametrize()
    "PLR2004",  # magic value used in comparison, ...
    "PT011",    # exception to broad
    "PLC2701",  # private import, but required for unit testing
    "PLC0415",  # local import
    "PT012",    # exception to broad
    "S311",     # standard pseudo-random generators are not suitable for cryptographic purposes
    "SLF001",   # private member access required for unit testing
    "S603",     # check for execution of untrusted input
    "ANN001",   # missing type annotation for function argument
    "ANN002",   # missing type annotation
    "ANN003",   # missing type annotation
    "ANN202",   # missing return type annotation
    "PTH123",   # use of open to be replaced with Path.open
    "DOC201",   # `return` is not documented in docstring
    "ASYNC230", # async functions should not open files with blocking methods like `open`
    "S104",     # bind to all ports
    "S607",     # subprocess with partial path
]

[tool.ruff.lint.extend-per-file-ignores]
"src/brave_search_python_client/responses/*.py" = [
    "N815", # mixedCase required to match the API response model of Brave Search API
]

[tool.ruff.format]
docstring-code-format = true

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.pytest.ini_options]
addopts = "-v --cov=brave_search_python_client --cov-report=term-missing --cov-report=xml:coverage.xml --cov-report=html:coverage_html"
testpaths = ["tests"]
python_files = ["*_test.py"]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"
env = ["COVERAGE_FILE=.coverage", "COVERAGE_PROCESS_START=pyproject.toml"]
markers = [
    "sequential: exclude from parallel test execution",
    "no_extras: tests that do require no extras installed",
]

[tool.coverage.run]
sigterm = true
relative_files = true
source = ["src"]
omit = ["src/starbridge/instrumentation/*"]
branch = true
parallel = true
concurrency = ["thread", "multiprocessing"]

[tool.coverage.paths]
source = ["src/"]


[tool.bumpversion]
current_version = "0.2.22"
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
serialize = ["{major}.{minor}.{patch}"]
search = "{current_version}"
replace = "{new_version}"
regex = false
ignore_missing_version = false
ignore_missing_files = false
tag = true
sign_tags = false
tag_name = "v{new_version}"
tag_message = "Bump version: {current_version} → {new_version}"
allow_dirty = false
commit = true
message = "Bump version: {current_version} → {new_version}"
commit_args = "--no-verify"
setup_hooks = []
pre_commit_hooks = [
    "uv sync",
    "git add uv.lock",
    "git-cliff --tag $BVHOOK_NEW_VERSION",
    "rm -f CHANGELOG.md.tmp",
    "git add CHANGELOG.md",
]
post_commit_hooks = []

[[tool.bumpversion.files]]
filename = "pyproject.toml"

[[tool.bumpversion.files]]
filename = "VERSION"

[[tool.bumpversion.files]]
filename = "sonar-project.properties"

[[tool.bumpversion.files]]
filename = "docs/source/conf.py"

[tool.git-cliff.remote.github]
owner = "helmut-hoffer-von-ankershoffen"
repo = "brave-search-python-client"

[tool.git-cliff.changelog]
output = "CHANGELOG.md"
render = true
# template for the changelog header
header = """
[🦁 Brave Search Python Client](https://helmuthva.gitbook.io/brave-search-api-client)\n
"""
# template for the changelog body
# https://keats.github.io/tera/docs/#introduction
body = """
{%- macro remote_url() -%}
  https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}
{%- endmacro -%}

{% macro print_commit(commit) -%}
    - {% if commit.scope %}*({{ commit.scope }})* {% endif %}\
        {% if commit.breaking %}[**breaking**] {% endif %}\
        {{ commit.message | upper_first }} - \
        ([{{ commit.id | truncate(length=7, end="") }}]({{ self::remote_url() }}/commit/{{ commit.id }}))\
{% endmacro -%}

{% if version %}\
    {% if previous.version %}\
        ## [{{ version | trim_start_matches(pat="v") }}]\
          ({{ self::remote_url() }}/compare/{{ previous.version }}..{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
    {% else %}\
        ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
    {% endif %}\
{% else %}\
    ## [unreleased]
{% endif %}\

{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | striptags | trim | upper_first }}
    {% for commit in commits
    | unique(attribute="message")
    | filter(attribute="scope")
    | sort(attribute="scope") %}
        {{ self::print_commit(commit=commit) }}
    {%- endfor %}
    {% for commit in commits
    | unique(attribute="message") %}
        {%- if not commit.scope -%}
            {{ self::print_commit(commit=commit) }}
        {% endif -%}
    {% endfor -%}
{% endfor -%}
{%- if github -%}
{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
  ## New Contributors ❤️
{% endif %}\
{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
  * @{{ contributor.username }} made their first contribution
    {%- if contributor.pr_number %} in \
      [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
    {%- endif %}
{%- endfor -%}
{%- endif %}
"""
# template for the changelog footer
footer = """
<!-- built with love in Berlin by Helmut Hoffer von Ankershoffen -->
"""
## [{{ version | trim_start_matches(pat="v") }}]\
## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
## [unreleased]
### {{ group | striptags | trim | upper_first }}
## New Contributors ❤️
# remove the leading and trailing whitespace from the templates
trim = true
# postprocessors
postprocessors = [
    { pattern = '<REPO>', replace = "https://github.com/orhun/git-cliff" }, # replace repository URL
]

[tool.git-cliff.git]
# parse the commits based on https://www.conventionalcommits.org
conventional_commits = true
# filter out the commits that are not conventional
filter_unconventional = true
# process each line of a commit as an individual commit
split_commits = false
# regex for preprocessing the commit messages
commit_preprocessors = [
    { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](<REPO>/issues/${2}))" },
]
# regex for parsing and grouping commits
commit_parsers = [
    { message = "^feat", group = "<!-- 0 -->⛰️  Features" },
    { message = "^fix", group = "<!-- 1 -->🐛 Bug Fixes" },
    { message = "^doc", group = "<!-- 3 -->📚 Documentation" },
    { message = "^perf", group = "<!-- 4 -->⚡ Performance" },
    { message = "^refactor\\(clippy\\)", skip = true },
    { message = "^refactor", group = "<!-- 2 -->🚜 Refactor" },
    { message = "^style", group = "<!-- 5 -->🎨 Styling" },
    { message = "^test", group = "<!-- 6 -->🧪 Testing" },
    { message = "^chore\\(release\\): prepare for", skip = true },
    { message = "^chore\\(deps.*\\)", skip = true },
    { message = "^chore\\(pr\\)", skip = true },
    { message = "^chore\\(pull\\)", skip = true },
    { message = "^chore\\(npm\\).*yarn\\.lock", skip = true },
    { message = "^chore|^ci", group = "<!-- 7 -->⚙️ Miscellaneous Tasks" },
    { body = ".*security", group = "<!-- 8 -->🛡️ Security" },
    { message = "^revert", group = "<!-- 9 -->◀️ Revert" },
]
# protect breaking changes from being skipped due to matching a skipping commit_parser
protect_breaking_commits = false
# filter out the commits that are not matched by commit parsers
filter_commits = false
# regex for matching git tags
tag_pattern = "v[0-9].*"
# regex for skipping tags
skip_tags = "beta|alpha"
# regex for ignoring tags
ignore_tags = "rc"
# sort the tags topologically
topo_order = false
# sort the commits inside sections by oldest/newest order
sort_commits = "newest"