bsqb 0.1.0__tar.gz

bsqb-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.venv/
+venv/
+*.egg

bsqb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bsqb contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bsqb-0.1.0/PKG-INFO

@@ -0,0 +1,332 @@
+Metadata-Version: 2.4
+Name: bsqb
+Version: 0.1.0
+Summary: Type-safe query builder for Brave Search operators
+Project-URL: Homepage, https://github.com/kodzghly/bsqb
+Project-URL: Documentation, https://github.com/kodzghly/bsqb#readme
+Project-URL: Repository, https://github.com/kodzghly/bsqb
+Project-URL: Issues, https://github.com/kodzghly/bsqb/issues
+Author: bsqb contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: brave,brave-search,query-builder,search,web-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bsqb
+
+[![CI](https://github.com/kodzghly/bsqb/actions/workflows/ci.yml/badge.svg)](https://github.com/kodzghly/bsqb/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/bsqb.svg)](https://pypi.org/project/bsqb/)
+[![Python versions](https://img.shields.io/pypi/pyversions/bsqb.svg)](https://pypi.org/project/bsqb/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**bsqb** (Brave Search Query Builder) is a type-safe, zero-dependency Python library for constructing [Brave Search](https://search.brave.com) query strings using the official search operators.
+
+It helps you build valid `q` parameters for the [Brave Search API](https://api-dashboard.search.brave.com/app/documentation/web-search) with a fluent API, automatic quoting, and validation against API limits.
+
+## Features
+
+- **Complete operator coverage** — All operators from the [official Brave Search documentation](https://api-dashboard.search.brave.com/documentation/resources/search-operators)
+- **Fluent API** — Chain methods for readable, composable queries
+- **Type-safe** — Full type hints and `py.typed` marker for mypy/Pylance
+- **Zero dependencies** — Lightweight core with no runtime requirements
+- **API limit validation** — Enforces the 400 character / 50 word limits on `q`
+- **Logical operators** — `AND`, `OR`, `NOT` with Python operators (`&`, `|`, `~`)
+
+## Installation
+
+```bash
+pip install bsqb
+```
+
+## Quick start
+
+```python
+from bsqb import Query
+
+# Basic query with field operators
+query = Query("machine learning").filetype("pdf").lang("en")
+print(query.build())
+# machine learning filetype:pdf lang:en
+
+# Use with the Brave Search API
+import urllib.parse
+import urllib.request
+
+params = urllib.parse.urlencode({"q": query.build()})
+url = f"https://api.search.brave.com/res/v1/web/search?{params}"
+request = urllib.request.Request(
+    url,
+    headers={"X-Subscription-Token": "YOUR_API_KEY"},
+)
+```
+
+## Supported operators
+
+| Operator | Method | Example output |
+| --- | --- | --- |
+| Plain term | `Query("term")` | `term` |
+| Exact phrase | `.phrase("exact phrase")` | `"exact phrase"` |
+| Force include | `.include("term")` | `+term` |
+| Exclude | `.exclude("term")` | `-term` |
+| File extension | `.ext("pdf")` | `ext:pdf` |
+| File type | `.filetype("pdf")` | `filetype:pdf` |
+| In title | `.intitle("2023")` | `intitle:2023` |
+| In body | `.inbody("keyword")` | `inbody:keyword` |
+| In page | `.inpage("keyword")` | `inpage:keyword` |
+| Language (ISO 639-1) | `.lang("es")` | `lang:es` |
+| Language alias | `.language("es")` | `language:es` |
+| Location (ISO 3166-1) | `.loc("gb")` | `loc:gb` |
+| Location alias | `.location("gb")` | `location:gb` |
+| Site / domain | `.site("example.com")` | `site:example.com` |
+| Logical AND | `.and_(other)` or `&` | `term1 AND term2` |
+| Logical OR | `.or_(other)` or `\|` | `term1 OR term2` |
+| Logical NOT | `.not_(other)` or `~` | `NOT term` |
+
+Operators can be placed anywhere in the query string, matching Brave Search behavior.
+
+## Examples
+
+### Official documentation examples
+
+```python
+from bsqb import Query
+
+# Academic research
+Query("climate change").filetype("pdf").site("edu").intitle("2024").build()
+# climate change filetype:pdf site:edu intitle:2024
+
+# Multilingual content
+Query("recettes cuisine").loc("ca").lang("fr").build()
+# recettes cuisine loc:ca lang:fr
+
+# Competitive analysis
+(
+    Query("AI startup")
+    .exclude("google")
+    .exclude("microsoft")
+    .exclude("amazon")
+    .exclude("meta")
+    .build()
+)
+# AI startup -google -microsoft -amazon -meta
+
+# Technical documentation
+(
+    Query("python")
+    .phrase("asyncio")
+    .intitle("documentation")
+    .site("docs.python.org")
+    .build()
+)
+# python "asyncio" intitle:documentation site:docs.python.org
+```
+
+### Logical operators
+
+```python
+from bsqb import Query, combine_and, combine_or
+
+# AND — visa info in English from UK sites
+Query("visa").loc("gb").and_(Query().lang("en")).build()
+# visa loc:gb AND lang:en
+
+# OR — travel requirements for Australia or New Zealand
+(
+    Query("travel requirements")
+    .inpage("australia")
+    .or_(Query().inpage("new zealand"))
+    .build()
+)
+# travel requirements inpage:australia OR inpage:"new zealand"
+
+# NOT — exclude a domain
+Query("brave search").not_(Query().site("brave.com")).build()
+# brave search NOT site:brave.com
+
+# Python operators
+(Query("coffee") | Query("tea")).exclude("starbucks").build()
+# coffee OR tea -starbucks
+
+# Combine multiple queries
+combine_and(Query("visa").loc("gb"), Query().lang("en")).build()
+combine_or(Query().site("reuters.com"), Query().site("bloomberg.com")).build()
+```
+
+### Advanced usage
+
+```python
+from bsqb import Query, phrase, raw, term
+
+# Build from AST nodes
+Query.from_nodes(term("python"), phrase("asyncio"), raw("site:docs.python.org"))
+
+# Wrap an existing query string
+Query.parse("machine learning filetype:pdf lang:en").build()
+
+# Skip validation for edge cases
+Query.parse("...").build(validate=False)
+```
+
+## Validation
+
+The Brave Search API enforces these limits on the `q` parameter:
+
+- Maximum **400 characters**
+- Maximum **50 words**
+- Query cannot be empty
+
+Call `.build()` to validate (default), or `.render()` / `str()` to get the string without validation:
+
+```python
+from bsqb import Query, QueryValidationError, EmptyQueryError
+
+query = Query("hello world")
+
+query.render()   # "hello world" — no validation
+query.build()    # "hello world" — validates limits
+
+try:
+    Query().build()
+except EmptyQueryError:
+    ...
+
+try:
+    Query.parse(" ".join(["word"] * 51)).build()
+except QueryValidationError as exc:
+    print(exc.query)
+```
+
+## Integration with Brave Search API
+
+Search operators are included in the `q` parameter. Set `operators=true` (the default) in API requests:
+
+```python
+import urllib.parse
+import urllib.request
+
+from bsqb import Query
+
+query = Query("python").phrase("asyncio").filetype("pdf").lang("en")
+
+params = {
+    "q": query.build(),
+    "count": "10",
+    "operators": "true",
+}
+url = "https://api.search.brave.com/res/v1/web/search?" + urllib.parse.urlencode(params)
+
+request = urllib.request.Request(
+    url,
+    headers={
+        "Accept": "application/json",
+        "X-Subscription-Token": "YOUR_API_KEY",
+    },
+)
+```
+
+For POST requests with long queries, pass the built string as the `q` field in the request body.
+
+## Development
+
+```bash
+git clone https://github.com/kodzghly/bsqb.git
+cd bsqb
+python -m pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint and type check
+ruff check src tests
+mypy src
+```
+
+## Publishing to PyPI
+
+This package uses [Hatchling](https://hatch.pypa.io/) as the build backend.
+
+### First-time setup
+
+1. Create accounts on [PyPI](https://pypi.org/account/register/) and [TestPyPI](https://test.pypi.org/account/register/)
+2. Enable [2FA](https://pypi.org/help/#twofa) on both accounts
+3. Create an API token at [pypi.org/manage/account/token/](https://pypi.org/manage/account/token/)
+
+### Test on TestPyPI
+
+```bash
+python -m pip install --upgrade build twine
+
+# Bump version in pyproject.toml and src/bsqb/__init__.py
+python -m build
+
+# Upload to TestPyPI
+twine upload --repository testpypi dist/*
+
+# Verify installation
+pip install --index-url https://test.pypi.org/simple/ bsqb
+```
+
+### Publish to PyPI
+
+```bash
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+### Recommended: publish via GitHub Actions
+
+Add trusted publishing on PyPI for your repository, then create a release workflow triggered by git tags:
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+```
+
+Create a GitHub release with tag `v0.1.0` to trigger publication.
+
+## References
+
+- [Brave Search Operators (API docs)](https://api-dashboard.search.brave.com/documentation/resources/search-operators)
+- [Brave Search Operators (help page)](https://search.brave.com/help/operators)
+- [Brave Web Search API](https://api-dashboard.search.brave.com/app/documentation/web-search)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bsqb-0.1.0/README.md

@@ -0,0 +1,300 @@
+# bsqb
+
+[![CI](https://github.com/kodzghly/bsqb/actions/workflows/ci.yml/badge.svg)](https://github.com/kodzghly/bsqb/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/bsqb.svg)](https://pypi.org/project/bsqb/)
+[![Python versions](https://img.shields.io/pypi/pyversions/bsqb.svg)](https://pypi.org/project/bsqb/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**bsqb** (Brave Search Query Builder) is a type-safe, zero-dependency Python library for constructing [Brave Search](https://search.brave.com) query strings using the official search operators.
+
+It helps you build valid `q` parameters for the [Brave Search API](https://api-dashboard.search.brave.com/app/documentation/web-search) with a fluent API, automatic quoting, and validation against API limits.
+
+## Features
+
+- **Complete operator coverage** — All operators from the [official Brave Search documentation](https://api-dashboard.search.brave.com/documentation/resources/search-operators)
+- **Fluent API** — Chain methods for readable, composable queries
+- **Type-safe** — Full type hints and `py.typed` marker for mypy/Pylance
+- **Zero dependencies** — Lightweight core with no runtime requirements
+- **API limit validation** — Enforces the 400 character / 50 word limits on `q`
+- **Logical operators** — `AND`, `OR`, `NOT` with Python operators (`&`, `|`, `~`)
+
+## Installation
+
+```bash
+pip install bsqb
+```
+
+## Quick start
+
+```python
+from bsqb import Query
+
+# Basic query with field operators
+query = Query("machine learning").filetype("pdf").lang("en")
+print(query.build())
+# machine learning filetype:pdf lang:en
+
+# Use with the Brave Search API
+import urllib.parse
+import urllib.request
+
+params = urllib.parse.urlencode({"q": query.build()})
+url = f"https://api.search.brave.com/res/v1/web/search?{params}"
+request = urllib.request.Request(
+    url,
+    headers={"X-Subscription-Token": "YOUR_API_KEY"},
+)
+```
+
+## Supported operators
+
+| Operator | Method | Example output |
+| --- | --- | --- |
+| Plain term | `Query("term")` | `term` |
+| Exact phrase | `.phrase("exact phrase")` | `"exact phrase"` |
+| Force include | `.include("term")` | `+term` |
+| Exclude | `.exclude("term")` | `-term` |
+| File extension | `.ext("pdf")` | `ext:pdf` |
+| File type | `.filetype("pdf")` | `filetype:pdf` |
+| In title | `.intitle("2023")` | `intitle:2023` |
+| In body | `.inbody("keyword")` | `inbody:keyword` |
+| In page | `.inpage("keyword")` | `inpage:keyword` |
+| Language (ISO 639-1) | `.lang("es")` | `lang:es` |
+| Language alias | `.language("es")` | `language:es` |
+| Location (ISO 3166-1) | `.loc("gb")` | `loc:gb` |
+| Location alias | `.location("gb")` | `location:gb` |
+| Site / domain | `.site("example.com")` | `site:example.com` |
+| Logical AND | `.and_(other)` or `&` | `term1 AND term2` |
+| Logical OR | `.or_(other)` or `\|` | `term1 OR term2` |
+| Logical NOT | `.not_(other)` or `~` | `NOT term` |
+
+Operators can be placed anywhere in the query string, matching Brave Search behavior.
+
+## Examples
+
+### Official documentation examples
+
+```python
+from bsqb import Query
+
+# Academic research
+Query("climate change").filetype("pdf").site("edu").intitle("2024").build()
+# climate change filetype:pdf site:edu intitle:2024
+
+# Multilingual content
+Query("recettes cuisine").loc("ca").lang("fr").build()
+# recettes cuisine loc:ca lang:fr
+
+# Competitive analysis
+(
+    Query("AI startup")
+    .exclude("google")
+    .exclude("microsoft")
+    .exclude("amazon")
+    .exclude("meta")
+    .build()
+)
+# AI startup -google -microsoft -amazon -meta
+
+# Technical documentation
+(
+    Query("python")
+    .phrase("asyncio")
+    .intitle("documentation")
+    .site("docs.python.org")
+    .build()
+)
+# python "asyncio" intitle:documentation site:docs.python.org
+```
+
+### Logical operators
+
+```python
+from bsqb import Query, combine_and, combine_or
+
+# AND — visa info in English from UK sites
+Query("visa").loc("gb").and_(Query().lang("en")).build()
+# visa loc:gb AND lang:en
+
+# OR — travel requirements for Australia or New Zealand
+(
+    Query("travel requirements")
+    .inpage("australia")
+    .or_(Query().inpage("new zealand"))
+    .build()
+)
+# travel requirements inpage:australia OR inpage:"new zealand"
+
+# NOT — exclude a domain
+Query("brave search").not_(Query().site("brave.com")).build()
+# brave search NOT site:brave.com
+
+# Python operators
+(Query("coffee") | Query("tea")).exclude("starbucks").build()
+# coffee OR tea -starbucks
+
+# Combine multiple queries
+combine_and(Query("visa").loc("gb"), Query().lang("en")).build()
+combine_or(Query().site("reuters.com"), Query().site("bloomberg.com")).build()
+```
+
+### Advanced usage
+
+```python
+from bsqb import Query, phrase, raw, term
+
+# Build from AST nodes
+Query.from_nodes(term("python"), phrase("asyncio"), raw("site:docs.python.org"))
+
+# Wrap an existing query string
+Query.parse("machine learning filetype:pdf lang:en").build()
+
+# Skip validation for edge cases
+Query.parse("...").build(validate=False)
+```
+
+## Validation
+
+The Brave Search API enforces these limits on the `q` parameter:
+
+- Maximum **400 characters**
+- Maximum **50 words**
+- Query cannot be empty
+
+Call `.build()` to validate (default), or `.render()` / `str()` to get the string without validation:
+
+```python
+from bsqb import Query, QueryValidationError, EmptyQueryError
+
+query = Query("hello world")
+
+query.render()   # "hello world" — no validation
+query.build()    # "hello world" — validates limits
+
+try:
+    Query().build()
+except EmptyQueryError:
+    ...
+
+try:
+    Query.parse(" ".join(["word"] * 51)).build()
+except QueryValidationError as exc:
+    print(exc.query)
+```
+
+## Integration with Brave Search API
+
+Search operators are included in the `q` parameter. Set `operators=true` (the default) in API requests:
+
+```python
+import urllib.parse
+import urllib.request
+
+from bsqb import Query
+
+query = Query("python").phrase("asyncio").filetype("pdf").lang("en")
+
+params = {
+    "q": query.build(),
+    "count": "10",
+    "operators": "true",
+}
+url = "https://api.search.brave.com/res/v1/web/search?" + urllib.parse.urlencode(params)
+
+request = urllib.request.Request(
+    url,
+    headers={
+        "Accept": "application/json",
+        "X-Subscription-Token": "YOUR_API_KEY",
+    },
+)
+```
+
+For POST requests with long queries, pass the built string as the `q` field in the request body.
+
+## Development
+
+```bash
+git clone https://github.com/kodzghly/bsqb.git
+cd bsqb
+python -m pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint and type check
+ruff check src tests
+mypy src
+```
+
+## Publishing to PyPI
+
+This package uses [Hatchling](https://hatch.pypa.io/) as the build backend.
+
+### First-time setup
+
+1. Create accounts on [PyPI](https://pypi.org/account/register/) and [TestPyPI](https://test.pypi.org/account/register/)
+2. Enable [2FA](https://pypi.org/help/#twofa) on both accounts
+3. Create an API token at [pypi.org/manage/account/token/](https://pypi.org/manage/account/token/)
+
+### Test on TestPyPI
+
+```bash
+python -m pip install --upgrade build twine
+
+# Bump version in pyproject.toml and src/bsqb/__init__.py
+python -m build
+
+# Upload to TestPyPI
+twine upload --repository testpypi dist/*
+
+# Verify installation
+pip install --index-url https://test.pypi.org/simple/ bsqb
+```
+
+### Publish to PyPI
+
+```bash
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+### Recommended: publish via GitHub Actions
+
+Add trusted publishing on PyPI for your repository, then create a release workflow triggered by git tags:
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+```
+
+Create a GitHub release with tag `v0.1.0` to trigger publication.
+
+## References
+
+- [Brave Search Operators (API docs)](https://api-dashboard.search.brave.com/documentation/resources/search-operators)
+- [Brave Search Operators (help page)](https://search.brave.com/help/operators)
+- [Brave Web Search API](https://api-dashboard.search.brave.com/app/documentation/web-search)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bsqb-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bsqb"
+version = "0.1.0"
+description = "Type-safe query builder for Brave Search operators"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "bsqb contributors" }]
+keywords = [
+    "brave",
+    "brave-search",
+    "search",
+    "query-builder",
+    "web-search",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.8",
+    "pytest>=8.0",
+    "pytest-cov>=4.1",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/kodzghly/bsqb"
+Documentation = "https://github.com/kodzghly/bsqb#readme"
+Repository = "https://github.com/kodzghly/bsqb"
+Issues = "https://github.com/kodzghly/bsqb/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bsqb"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/bsqb", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["bsqb"]
+
+[tool.coverage.run]
+source = ["bsqb"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true

bsqb-0.1.0/src/bsqb/__init__.py

@@ -0,0 +1,53 @@
+"""Brave Search query builder (bsqb)."""
+
+from bsqb.builder import Query, combine_and, combine_or, phrase, raw, term
+from bsqb.exceptions import BsqbError, EmptyQueryError, QueryValidationError
+from bsqb.nodes import (
+    BinaryLogical,
+    Exclude,
+    Field,
+    Include,
+    Node,
+    Not,
+    Phrase,
+    Raw,
+    Sequence,
+    Term,
+)
+from bsqb.operators import (
+    MAX_QUERY_CHARACTERS,
+    MAX_QUERY_WORDS,
+    FieldOperator,
+    LogicalOperator,
+)
+from bsqb.validation import count_words, validate_query
+
+__all__ = [
+    "MAX_QUERY_CHARACTERS",
+    "MAX_QUERY_WORDS",
+    "BinaryLogical",
+    "BsqbError",
+    "EmptyQueryError",
+    "Exclude",
+    "Field",
+    "FieldOperator",
+    "Include",
+    "LogicalOperator",
+    "Node",
+    "Not",
+    "Phrase",
+    "Query",
+    "QueryValidationError",
+    "Raw",
+    "Sequence",
+    "Term",
+    "combine_and",
+    "combine_or",
+    "count_words",
+    "phrase",
+    "raw",
+    "term",
+    "validate_query",
+]
+
+__version__ = "0.1.0"

bsqb-0.1.0/src/bsqb/builder.py

@@ -0,0 +1,274 @@
+"""Fluent query builder for Brave Search operators."""
+
+from __future__ import annotations
+
+from bsqb.exceptions import EmptyQueryError
+from bsqb.nodes import (
+    BinaryLogical,
+    Exclude,
+    Field,
+    Include,
+    Node,
+    Not,
+    Phrase,
+    Raw,
+    Sequence,
+    Term,
+    empty_node,
+)
+from bsqb.operators import FieldOperator, LogicalOperator
+from bsqb.validation import validate_query
+
+__all__ = [
+    "Query",
+    "phrase",
+    "raw",
+    "term",
+]
+
+
+def term(value: str) -> Term:
+    """Create a plain search term node."""
+    return Term(value)
+
+
+def phrase(value: str) -> Phrase:
+    """Create an exact phrase match node."""
+    return Phrase(value)
+
+
+def raw(value: str) -> Raw:
+    """Create a raw query fragment node."""
+    return Raw(value)
+
+
+class Query:
+    """
+    Fluent builder for Brave Search query strings.
+
+    Supports all operators documented at:
+    https://api-dashboard.search.brave.com/documentation/resources/search-operators
+
+    Examples:
+        >>> str(Query("machine learning").filetype("pdf").lang("en"))
+        'machine learning filetype:pdf lang:en'
+
+        >>> str(Query("visa").loc("gb").and_(Query().lang("en")))
+        'visa loc:gb AND lang:en'
+    """
+
+    __slots__ = ("_node",)
+
+    def __init__(
+        self,
+        *parts: str | Node,
+        _node: Node | None = None,
+    ) -> None:
+        if _node is not None:
+            self._node = _node
+            return
+
+        nodes: list[Node] = []
+        for part in parts:
+            if isinstance(part, Node):
+                nodes.append(part)
+            elif isinstance(part, str) and part:
+                nodes.append(Term(part))
+
+        if not nodes:
+            self._node = empty_node()
+        elif len(nodes) == 1:
+            self._node = nodes[0]
+        else:
+            self._node = Sequence(tuple(nodes))
+
+    @classmethod
+    def from_nodes(cls, *nodes: Node) -> Query:
+        """Create a query from explicit AST nodes."""
+        if not nodes:
+            return cls(_node=empty_node())
+        if len(nodes) == 1:
+            return cls(_node=nodes[0])
+        return cls(_node=Sequence(tuple(nodes)))
+
+    @classmethod
+    def parse(cls, value: str) -> Query:
+        """
+        Wrap a pre-built query string without parsing.
+
+        Use this when you already have a valid Brave Search query string.
+        """
+        stripped = value.strip()
+        if not stripped:
+            return cls()
+        return cls(_node=Raw(stripped))
+
+    def _append(self, node: Node) -> Query:
+        current = self._node
+        if isinstance(current, Sequence):
+            return Query(_node=Sequence((*current.parts, node)))
+        if isinstance(current, (BinaryLogical, Not)) or not current:
+            return Query(_node=Sequence((current, node)) if current else node)
+        return Query(_node=Sequence((current, node)))
+
+    def _logical(self, operator: LogicalOperator, other: Query) -> Query:
+        return Query(_node=BinaryLogical(operator, self._node, other._node))
+
+    # --- Content terms -------------------------------------------------
+
+    def term(self, value: str) -> Query:
+        """Append a plain search term."""
+        return self._append(Term(value))
+
+    def phrase(self, value: str) -> Query:
+        """Append an exact phrase match."""
+        return self._append(Phrase(value))
+
+    def include(self, value: str) -> Query:
+        """Force inclusion of a term (+term)."""
+        return self._append(Include(value))
+
+    def exclude(self, value: str) -> Query:
+        """Exclude a term (-term)."""
+        return self._append(Exclude(value))
+
+    def raw(self, value: str) -> Query:
+        """Append a raw query fragment."""
+        return self._append(Raw(value))
+
+    # --- Field operators -----------------------------------------------
+
+    def ext(self, extension: str) -> Query:
+        """Filter by file extension (ext:)."""
+        return self._append(Field(FieldOperator.EXT, extension.lstrip(".")))
+
+    def filetype(self, filetype: str) -> Query:
+        """Filter by file type (filetype:)."""
+        return self._append(Field(FieldOperator.FILETYPE, filetype.lstrip(".")))
+
+    def intitle(self, value: str) -> Query:
+        """Search in page title (intitle:)."""
+        return self._append(Field(FieldOperator.INTITLE, value))
+
+    def inbody(self, value: str) -> Query:
+        """Search in page body (inbody:)."""
+        return self._append(Field(FieldOperator.INBODY, value))
+
+    def inpage(self, value: str) -> Query:
+        """Search in title or body (inpage:)."""
+        return self._append(Field(FieldOperator.INPAGE, value))
+
+    def lang(self, code: str) -> Query:
+        """Filter by language ISO 639-1 code (lang:)."""
+        return self._append(Field(FieldOperator.LANG, code.lower()))
+
+    def language(self, code: str) -> Query:
+        """Alias for lang() using the language: operator."""
+        return self._append(Field(FieldOperator.LANGUAGE, code.lower()))
+
+    def loc(self, code: str) -> Query:
+        """Filter by country ISO 3166-1 alpha-2 code (loc:)."""
+        return self._append(Field(FieldOperator.LOC, code.lower()))
+
+    def location(self, code: str) -> Query:
+        """Alias for loc() using the location: operator."""
+        return self._append(Field(FieldOperator.LOCATION, code.lower()))
+
+    def site(self, domain: str) -> Query:
+        """Limit results to a domain (site:)."""
+        normalized = domain.removeprefix("https://").removeprefix("http://")
+        normalized = normalized.removeprefix("www.").rstrip("/")
+        return self._append(Field(FieldOperator.SITE, normalized))
+
+    # --- Logical operators ---------------------------------------------
+
+    def and_(self, other: Query) -> Query:
+        """Combine with AND (both conditions required)."""
+        return self._logical(LogicalOperator.AND, other)
+
+    def or_(self, other: Query) -> Query:
+        """Combine with OR (either condition sufficient)."""
+        return self._logical(LogicalOperator.OR, other)
+
+    def not_(self, other: Query | None = None) -> Query:
+        """
+        Negate a condition with NOT.
+
+        When called with another query, appends ``NOT`` to the current query.
+        When called without an argument, negates the current query.
+        """
+        if other is None:
+            return Query(_node=Not(self._node))
+        return Query(_node=Sequence((self._node, Not(other._node))))
+
+    # --- Python operators for ergonomics --------------------------------
+
+    def __and__(self, other: Query) -> Query:
+        return self.and_(other)
+
+    def __or__(self, other: Query) -> Query:
+        return self.or_(other)
+
+    def __invert__(self) -> Query:
+        return self.not_()
+
+    # --- Output --------------------------------------------------------
+
+    def render(self) -> str:
+        """Render the query string without validation."""
+        return self._node.render()
+
+    def build(self, *, validate: bool = True) -> str:
+        """
+        Build and optionally validate the query string.
+
+        Args:
+            validate: When True (default), enforce Brave Search API limits.
+
+        Raises:
+            EmptyQueryError: When the query is empty.
+            QueryValidationError: When limits are exceeded.
+        """
+        rendered = self.render()
+        if not rendered:
+            raise EmptyQueryError()
+        if validate:
+            return validate_query(rendered)
+        return rendered
+
+    def __str__(self) -> str:
+        return self.render()
+
+    def __repr__(self) -> str:
+        return f"Query({self.render()!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Query):
+            return NotImplemented
+        return self.render() == other.render()
+
+    def __hash__(self) -> int:
+        return hash(self.render())
+
+    def __bool__(self) -> bool:
+        return bool(self.render())
+
+
+def combine_and(*queries: Query) -> Query:
+    """Combine multiple queries with AND."""
+    if not queries:
+        return Query()
+    result = queries[0]
+    for query in queries[1:]:
+        result = result.and_(query)
+    return result
+
+
+def combine_or(*queries: Query) -> Query:
+    """Combine multiple queries with OR."""
+    if not queries:
+        return Query()
+    result = queries[0]
+    for query in queries[1:]:
+        result = result.or_(query)
+    return result

bsqb-0.1.0/src/bsqb/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exceptions for bsqb."""
+
+from __future__ import annotations
+
+
+class BsqbError(Exception):
+    """Base exception for all bsqb errors."""
+
+
+class QueryValidationError(BsqbError):
+    """Raised when a built query violates Brave Search API limits."""
+
+    def __init__(self, message: str, *, query: str | None = None) -> None:
+        super().__init__(message)
+        self.query = query
+
+
+class EmptyQueryError(QueryValidationError):
+    """Raised when attempting to build an empty query."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Query cannot be empty. "
+            "The Brave Search API requires a non-empty q parameter."
+        )

bsqb-0.1.0/src/bsqb/nodes.py

@@ -0,0 +1,150 @@
+"""Abstract syntax tree nodes for Brave Search queries."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from bsqb.operators import FieldOperator, LogicalOperator
+
+
+def _format_operand(value: str, *, quote: bool = False) -> str:
+    """Format an operator operand, quoting when it contains whitespace."""
+    if quote or any(char.isspace() for char in value):
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    return value
+
+
+def _format_term(value: str) -> str:
+    """Format a plain search term."""
+    return value
+
+
+class Node(ABC):
+    """Base class for all query AST nodes."""
+
+    @abstractmethod
+    def render(self) -> str:
+        """Render this node to a Brave Search query string."""
+
+    def __bool__(self) -> bool:
+        return bool(self.render())
+
+
+@dataclass(frozen=True, slots=True)
+class Term(Node):
+    """A plain search term."""
+
+    value: str
+
+    def render(self) -> str:
+        return _format_term(self.value)
+
+
+@dataclass(frozen=True, slots=True)
+class Phrase(Node):
+    """An exact phrase match wrapped in double quotes."""
+
+    value: str
+
+    def render(self) -> str:
+        value = self.value
+        escaped = (
+            ""
+            if not value
+            else value.replace("\\", "\\\\").replace('"', '\\"')
+        )
+        return f'"{escaped}"'
+
+
+@dataclass(frozen=True, slots=True)
+class Include(Node):
+    """Force inclusion of a term (+term)."""
+
+    value: str
+
+    def render(self) -> str:
+        return f"+{_format_term(self.value)}"
+
+
+@dataclass(frozen=True, slots=True)
+class Exclude(Node):
+    """Exclude a term (-term)."""
+
+    value: str
+
+    def render(self) -> str:
+        return f"-{_format_term(self.value)}"
+
+
+@dataclass(frozen=True, slots=True)
+class Field(Node):
+    """A field operator such as site:, lang:, or filetype:."""
+
+    operator: FieldOperator
+    value: str
+
+    def render(self) -> str:
+        return f"{self.operator.value}:{_format_operand(self.value)}"
+
+
+@dataclass(frozen=True, slots=True)
+class Raw(Node):
+    """A pre-formatted query fragment for advanced use cases."""
+
+    value: str
+
+    def render(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class Sequence(Node):
+    """A space-separated sequence of query parts."""
+
+    parts: tuple[Node, ...]
+
+    def render(self) -> str:
+        rendered = [part.render() for part in self.parts if part.render()]
+        return " ".join(rendered)
+
+
+@dataclass(frozen=True, slots=True)
+class BinaryLogical(Node):
+    """A binary logical expression (AND / OR)."""
+
+    operator: LogicalOperator
+    left: Node
+    right: Node
+
+    def render(self) -> str:
+        left = self.left.render()
+        right = self.right.render()
+        op = self.operator.value
+        if isinstance(self.left, BinaryLogical) and self.left.operator != self.operator:
+            left = f"({left})"
+        if (
+            isinstance(self.right, BinaryLogical)
+            and self.right.operator != self.operator
+        ):
+            right = f"({right})"
+        return f"{left} {op} {right}"
+
+
+@dataclass(frozen=True, slots=True)
+class Not(Node):
+    """A NOT logical expression."""
+
+    operand: Node
+
+    def render(self) -> str:
+        operand = self.operand.render()
+        if isinstance(self.operand, BinaryLogical):
+            operand = f"({operand})"
+        return f"{LogicalOperator.NOT.value} {operand}"
+
+
+def empty_node() -> Sequence:
+    """Return an empty sequence node."""
+    return Sequence(())

bsqb-0.1.0/src/bsqb/operators.py

@@ -0,0 +1,33 @@
+"""Brave Search operator definitions based on official documentation."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class FieldOperator(str, Enum):
+    """Field operators supported by Brave Search."""
+
+    EXT = "ext"
+    FILETYPE = "filetype"
+    INTITLE = "intitle"
+    INBODY = "inbody"
+    INPAGE = "inpage"
+    LANG = "lang"
+    LANGUAGE = "language"
+    LOC = "loc"
+    LOCATION = "location"
+    SITE = "site"
+
+
+class LogicalOperator(str, Enum):
+    """Logical operators supported by Brave Search (must be uppercase)."""
+
+    AND = "AND"
+    OR = "OR"
+    NOT = "NOT"
+
+
+# Brave Search API query limits.
+MAX_QUERY_CHARACTERS = 400
+MAX_QUERY_WORDS = 50

bsqb-0.1.0/src/bsqb/validation.py

@@ -0,0 +1,47 @@
+"""Validation helpers for Brave Search query limits."""
+
+from __future__ import annotations
+
+import re
+
+from bsqb.exceptions import EmptyQueryError, QueryValidationError
+from bsqb.operators import MAX_QUERY_CHARACTERS, MAX_QUERY_WORDS
+
+_WORD_PATTERN = re.compile(r"\S+")
+
+
+def count_words(query: str) -> int:
+    """Count words in a query string."""
+    return len(_WORD_PATTERN.findall(query))
+
+
+def validate_query(query: str) -> str:
+    """
+    Validate a query against Brave Search API limits.
+
+    Returns the query unchanged when valid.
+
+    Raises:
+        EmptyQueryError: When the query is empty or whitespace-only.
+        QueryValidationError: When the query exceeds character or word limits.
+    """
+    normalized = query.strip()
+    if not normalized:
+        raise EmptyQueryError()
+
+    if len(normalized) > MAX_QUERY_CHARACTERS:
+        raise QueryValidationError(
+            f"Query exceeds the maximum of {MAX_QUERY_CHARACTERS} characters "
+            f"({len(normalized)} given).",
+            query=normalized,
+        )
+
+    word_count = count_words(normalized)
+    if word_count > MAX_QUERY_WORDS:
+        raise QueryValidationError(
+            f"Query exceeds the maximum of {MAX_QUERY_WORDS} words "
+            f"({word_count} given).",
+            query=normalized,
+        )
+
+    return normalized