surfx 0.2.0__py3-none-any.whl

surfx/__init__.py

@@ -0,0 +1,5 @@
+"""Surfx - a fast, clean, terminal-first web search CLI."""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

surfx/__main__.py

@@ -0,0 +1,4 @@
+from surfx.cli import app
+
+if __name__ == "__main__":
+    app()

surfx/browser.py

@@ -0,0 +1,25 @@
+"""Cross-platform browser opening.
+
+Surfx never downloads or executes the content of a search result. Opening a
+result simply hands its URL to the operating system's default browser via
+the standard library ``webbrowser`` module.
+"""
+
+from __future__ import annotations
+
+import webbrowser
+
+
+def open_url(url: str) -> bool:
+    """Open ``url`` in the user's default browser.
+
+    Returns ``True`` if the browser was successfully launched, ``False``
+    otherwise. Never raises: environments without a usable browser (e.g.
+    headless CI) should degrade gracefully.
+    """
+    if not (url.startswith("http://") or url.startswith("https://")):
+        return False
+    try:
+        return webbrowser.open(url, new=2)
+    except Exception:
+        return False

surfx/cli.py

@@ -0,0 +1,337 @@
+"""The Surfx command-line interface."""
+
+from __future__ import annotations
+
+import json
+import platform
+import socket
+import sys
+from typing import Optional
+
+import httpx
+import typer
+from rich.prompt import Confirm
+from typer.core import TyperGroup
+
+from surfx import __version__
+from surfx import terminal
+from surfx.browser import open_url
+from surfx.config import Settings, load_settings, write_file_setting
+from surfx.errors import SurfxError
+from surfx.models import SearchResponse
+from surfx.providers import PROVIDERS
+from surfx.services.cache import ResultCache
+from surfx.services.search import build_provider, run_search
+
+DEFAULT_COMMAND = "search"
+
+INTERACTIVE_HELP = """\
+Commands:
+  /help    Show this help
+  /clear   Clear the screen
+  /exit    Leave interactive mode
+  /quit    Leave interactive mode (alias for /exit)
+"""
+
+
+class DefaultCommandGroup(TyperGroup):
+    """A Click/Typer group that falls back to the ``search`` command.
+
+    This is what lets ``surfx "some query"`` work without typing
+    ``surfx search "some query"``, while still supporting real subcommands
+    like ``surfx config`` and ``surfx doctor``.
+    """
+
+    def resolve_command(self, ctx, args):  # type: ignore[override]
+        if not args or (args[0] not in self.commands and not args[0].startswith("-")):
+            args = [DEFAULT_COMMAND, *args]
+        return super().resolve_command(ctx, args)
+
+
+app = typer.Typer(
+    cls=DefaultCommandGroup,
+    add_completion=True,
+    no_args_is_help=False,
+    help="Surfx - search the web from your terminal.",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+config_app = typer.Typer(help="Inspect or change Surfx configuration.")
+app.add_typer(config_app, name="config")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"surfx {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True, help="Show the version and exit."
+    ),
+) -> None:
+    """Surfx - search the web from your terminal."""
+
+
+def _resolve_settings(
+    *, provider: str | None, limit: int | None, no_color: bool | None
+) -> Settings:
+    settings = load_settings()
+    return settings.with_overrides(provider=provider, limit=limit, no_color=no_color)
+
+
+def _handle_error(console, error: Exception, *, debug: bool) -> None:
+    if debug:
+        raise error
+    if isinstance(error, SurfxError):
+        terminal.print_error(console, error.message)
+    else:
+        terminal.print_error(console, str(error) or error.__class__.__name__)
+
+
+@app.command(DEFAULT_COMMAND, help="Search the web. This is Surfx's default command.")
+def search_command(
+    query: Optional[str] = typer.Argument(
+        None, help='The search query, e.g. surfx "python asyncio tutorial"'
+    ),
+    limit: Optional[int] = typer.Option(
+        None, "--limit", "-n", help="Number of results to return (1-50)."
+    ),
+    provider: Optional[str] = typer.Option(
+        None, "--provider", help="Search provider to use.", show_default=False
+    ),
+    as_json: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON on stdout only."
+    ),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable colored/styled output."),
+    open_rank: Optional[int] = typer.Option(
+        None, "--open", help="Open the result with this rank in your browser.", metavar="N"
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Skip the confirmation prompt when using --open."
+    ),
+    debug: bool = typer.Option(False, "--debug", help="Show full tracebacks on error."),
+) -> None:
+    out_console = terminal.make_console(no_color=no_color)
+    err_console = terminal.make_console(no_color=no_color, stderr=True)
+
+    settings = _resolve_settings(provider=provider, limit=limit, no_color=no_color)
+
+    if not query:
+        _interactive_loop(settings, debug=debug)
+        return
+
+    _run_single_search(
+        query,
+        settings,
+        as_json=as_json,
+        open_rank=open_rank,
+        auto_confirm=yes or as_json,
+        debug=debug,
+        out_console=out_console,
+        err_console=err_console,
+    )
+
+
+def _run_single_search(
+    query: str,
+    settings: Settings,
+    *,
+    as_json: bool,
+    open_rank: int | None,
+    auto_confirm: bool,
+    debug: bool,
+    out_console,
+    err_console,
+) -> None:
+    cache = ResultCache(ttl_seconds=settings.cache_ttl_seconds)
+
+    try:
+        if as_json:
+            response = run_search(query, settings, cache=cache, allow_empty=True)
+        else:
+            with terminal.loading_status(out_console):
+                response = run_search(query, settings, cache=cache)
+    except SurfxError as error:
+        _handle_error(err_console, error, debug=debug)
+        raise typer.Exit(code=1) from None
+    except httpx.HTTPError as error:
+        _handle_error(err_console, error, debug=debug)
+        raise typer.Exit(code=1) from None
+
+    if as_json:
+        _print_json(response)
+    else:
+        terminal.print_results(out_console, response)
+
+    if open_rank is not None:
+        _maybe_open(response, open_rank, auto_confirm=auto_confirm, console=out_console)
+
+
+def _print_json(response: SearchResponse) -> None:
+    sys.stdout.write(json.dumps(response.to_dict(), indent=2))
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+
+
+def _maybe_open(
+    response: SearchResponse, rank: int, *, auto_confirm: bool, console
+) -> None:
+    if rank < 1 or rank > len(response.results):
+        terminal.print_error(console, f"No result with rank {rank}.")
+        return
+
+    result = response.results[rank - 1]
+
+    if not auto_confirm:
+        should_open = Confirm.ask(f"Open result [{rank}] {result.title!r}?", default=False)
+        if not should_open:
+            return
+
+    if open_url(result.url):
+        terminal.print_success(console, f"Opened {result.url}")
+    else:
+        terminal.print_error(console, f"Could not open a browser for {result.url}")
+
+
+def _interactive_loop(settings: Settings, *, debug: bool) -> None:
+    console = terminal.make_console(no_color=settings.no_color)
+    err_console = terminal.make_console(no_color=settings.no_color, stderr=True)
+    cache = ResultCache(ttl_seconds=settings.cache_ttl_seconds)
+
+    terminal.print_banner(console)
+    console.print()
+
+    while True:
+        try:
+            raw = console.input("[bold cyan]Search >[/bold cyan] ")
+        except (EOFError, KeyboardInterrupt):
+            console.print()
+            break
+
+        query = raw.strip()
+        if not query:
+            continue
+
+        if query in {"/exit", "/quit"}:
+            break
+        if query == "/help":
+            console.print(INTERACTIVE_HELP)
+            continue
+        if query == "/clear":
+            console.clear()
+            continue
+
+        try:
+            with terminal.loading_status(console):
+                response = run_search(query, settings, cache=cache)
+            terminal.print_results(console, response)
+        except SurfxError as error:
+            _handle_error(err_console, error, debug=debug)
+        except httpx.HTTPError as error:
+            _handle_error(err_console, error, debug=debug)
+
+
+@config_app.callback(invoke_without_command=True)
+def config_show(ctx: typer.Context) -> None:
+    """Show the current configuration (secrets are never printed)."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    console = terminal.make_console()
+    settings = load_settings()
+    data = settings.redacted_dict()
+
+    terminal.print_banner(console, "Configuration")
+    console.print()
+    for key, value in data.items():
+        console.print(f"  [bold]{key}[/bold]: {value}")
+
+
+@config_app.command("set")
+def config_set(key: str, value: str) -> None:
+    """Set a non-secret configuration value, e.g. 'surfx config set searxng_url https://...'."""
+    console = terminal.make_console()
+    try:
+        write_file_setting(key, value)
+    except SurfxError as error:
+        terminal.print_error(console, error.message)
+        raise typer.Exit(code=1) from None
+
+    terminal.print_success(console, f"Set {key} = {value}")
+
+
+@app.command()
+def doctor() -> None:
+    """Check that Surfx is installed and configured correctly."""
+    console = terminal.make_console()
+    settings = load_settings()
+
+    terminal.print_banner(console, "Doctor")
+    console.print()
+
+    checks: list[tuple[bool, str]] = [
+        (True, f"Python {platform.python_version()}"),
+        (True, "Configuration loaded"),
+        (_check_network(), "Internet connectivity available"),
+    ]
+
+    provider_ok = settings.provider in PROVIDERS
+    checks.append(
+        (
+            provider_ok,
+            f"Provider '{settings.provider}' is {'known' if provider_ok else 'NOT recognized'}",
+        )
+    )
+
+    if provider_ok:
+        checks.extend(_check_provider(settings))
+    else:
+        available = ", ".join(sorted(PROVIDERS))
+        checks.append((False, f"Available providers: {available}"))
+
+    for ok, label in checks:
+        mark = "[green]\u2713[/green]" if ok else "[red]\u2717[/red]"
+        console.print(f"{mark} {label}")
+
+    console.print()
+    if all(ok for ok, _ in checks):
+        terminal.print_success(console, "Surfx is ready.")
+    else:
+        terminal.print_error(console, "Surfx is not fully configured. See above.")
+        raise typer.Exit(code=1)
+
+
+def _check_provider(settings: Settings) -> list[tuple[bool, str]]:
+    """Validate configuration and, where supported, check live connectivity."""
+    results: list[tuple[bool, str]] = []
+
+    try:
+        provider = build_provider(settings.provider, settings)
+        provider.validate_config()
+    except SurfxError as error:
+        results.append((False, error.message))
+        return results
+
+    results.append((True, f"'{settings.provider}' provider is configured"))
+
+    check_connectivity = getattr(provider, "check_connectivity", None)
+    if callable(check_connectivity):
+        ok, message = check_connectivity()
+        results.append((ok, message))
+
+    return results
+
+
+def _check_network(host: str = "8.8.8.8", port: int = 53, timeout: float = 2.0) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+if __name__ == "__main__":
+    app()

surfx/config.py

@@ -0,0 +1,213 @@
+"""Configuration handling for Surfx.
+
+Precedence (highest to lowest):
+
+    1. CLI arguments (applied by the caller, not here)
+    2. Environment variables
+    3. Config file (``~/.config/surfx/config.toml``)
+    4. Built-in defaults
+
+Secret-shaped values (API keys, tokens, etc.) are intentionally *not* read
+from the config file - they must come from environment variables. This
+keeps ``config.toml`` safe to version-control or share by accident. Plain
+configuration such as the SearXNG instance URL is not a secret and may live
+in either place.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - repo targets 3.11+
+    import tomli as tomllib
+
+import tomli_w
+
+from surfx.errors import ConfigurationError
+
+DEFAULT_PROVIDER = "searxng"
+DEFAULT_LIMIT = 10
+MIN_LIMIT = 1
+MAX_LIMIT = 50
+
+ENV_PROVIDER = "SURFX_PROVIDER"
+ENV_LIMIT = "SURFX_LIMIT"
+ENV_SEARXNG_URL = "SURFX_SEARXNG_URL"
+ENV_NO_COLOR = "SURFX_NO_COLOR"
+ENV_CACHE_ENABLED = "SURFX_CACHE_ENABLED"
+ENV_CACHE_TTL = "SURFX_CACHE_TTL_SECONDS"
+
+# Config file keys that are allowed to live on disk. Deliberately excludes
+# anything credential-shaped - "searxng_url" is allowed because it's a
+# plain endpoint address, not a secret.
+_ALLOWED_FILE_KEYS = {
+    "provider",
+    "limit",
+    "no_color",
+    "cache_enabled",
+    "cache_ttl_seconds",
+    "searxng_url",
+}
+_SECRET_LOOKING_SUFFIXES = ("key", "secret", "token", "password", "cx")
+
+
+def default_config_path() -> Path:
+    xdg_config = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg_config) if xdg_config else Path.home() / ".config"
+    return base / "surfx" / "config.toml"
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """Fully resolved Surfx settings."""
+
+    provider: str = DEFAULT_PROVIDER
+    limit: int = DEFAULT_LIMIT
+    no_color: bool = False
+    cache_enabled: bool = False
+    cache_ttl_seconds: int = 300
+    searxng_url: str | None = None
+    config_path: Path | None = None
+
+    def with_overrides(self, **kwargs: Any) -> Settings:
+        """Return a copy with only the non-``None`` overrides applied."""
+        overrides = {k: v for k, v in kwargs.items() if v is not None}
+        return replace(self, **overrides)
+
+    def redacted_dict(self) -> dict[str, Any]:
+        """Settings as a dict safe to print.
+
+        ``searxng_url`` is not a secret, so its value is shown directly;
+        there is nothing else in the current settings worth redacting.
+        """
+        return {
+            "provider": self.provider,
+            "limit": self.limit,
+            "no_color": self.no_color,
+            "cache_enabled": self.cache_enabled,
+            "cache_ttl_seconds": self.cache_ttl_seconds,
+            "searxng_url": self.searxng_url or "(not set)",
+            "config_path": str(self.config_path) if self.config_path else None,
+        }
+
+
+def _read_config_file(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        raw = path.read_bytes()
+        data = tomllib.loads(raw.decode("utf-8"))
+    except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigurationError(
+            f"Could not read config file at {path}: {exc}"
+        ) from exc
+
+    if not isinstance(data, dict):
+        raise ConfigurationError(f"Config file at {path} must contain a table of settings.")
+
+    # Silently ignore (never surface) anything that looks like a secret, and
+    # ignore unknown keys rather than failing hard on forward-compatible files.
+    return {k: v for k, v in data.items() if k in _ALLOWED_FILE_KEYS}
+
+
+def _env_bool(name: str) -> bool | None:
+    value = os.environ.get(name)
+    if value is None:
+        return None
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _env_int(name: str) -> int | None:
+    value = os.environ.get(name)
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError as exc:
+        raise ConfigurationError(f"{name} must be an integer, got {value!r}.") from exc
+
+
+def load_settings(config_path: Path | None = None) -> Settings:
+    """Load settings from the config file and environment, defaults included.
+
+    CLI-level overrides are intentionally applied afterwards by the caller
+    (see ``cli.py``) via :meth:`Settings.with_overrides`.
+    """
+    path = config_path or default_config_path()
+    file_values = _read_config_file(path)
+
+    settings = Settings(config_path=path)
+    settings = settings.with_overrides(
+        provider=file_values.get("provider"),
+        limit=file_values.get("limit"),
+        no_color=file_values.get("no_color"),
+        cache_enabled=file_values.get("cache_enabled"),
+        cache_ttl_seconds=file_values.get("cache_ttl_seconds"),
+        searxng_url=file_values.get("searxng_url"),
+    )
+
+    settings = settings.with_overrides(
+        provider=os.environ.get(ENV_PROVIDER),
+        limit=_env_int(ENV_LIMIT),
+        no_color=_env_bool(ENV_NO_COLOR),
+        cache_enabled=_env_bool(ENV_CACHE_ENABLED),
+        cache_ttl_seconds=_env_int(ENV_CACHE_TTL),
+        searxng_url=os.environ.get(ENV_SEARXNG_URL),
+    )
+
+    return settings
+
+
+def write_file_setting(key: str, value: str, config_path: Path | None = None) -> Settings:
+    """Persist a single non-secret setting to the config file and return the
+    reloaded settings.
+    """
+    if key not in _ALLOWED_FILE_KEYS:
+        raise ConfigurationError(
+            f"'{key}' cannot be stored in the config file. "
+            "Secrets must be set via environment variables instead."
+        )
+    if any(key.endswith(suffix) for suffix in _SECRET_LOOKING_SUFFIXES):
+        raise ConfigurationError(
+            f"Refusing to store '{key}' in the config file because it looks like a secret. "
+            "Use an environment variable instead."
+        )
+
+    path = config_path or default_config_path()
+    existing = _read_config_file(path)
+
+    coerced: Any = value
+    if key == "limit":
+        try:
+            coerced = int(value)
+        except ValueError as exc:
+            raise ConfigurationError(f"'limit' must be an integer, got {value!r}.") from exc
+        if not (MIN_LIMIT <= coerced <= MAX_LIMIT):
+            raise ConfigurationError(f"'limit' must be between {MIN_LIMIT} and {MAX_LIMIT}.")
+    elif key in {"no_color", "cache_enabled"}:
+        coerced = value.strip().lower() in {"1", "true", "yes", "on"}
+    elif key == "cache_ttl_seconds":
+        try:
+            coerced = int(value)
+        except ValueError as exc:
+            raise ConfigurationError(
+                f"'cache_ttl_seconds' must be an integer, got {value!r}."
+            ) from exc
+
+    existing[key] = coerced
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(tomli_w.dumps(existing).encode("utf-8"))
+
+    return load_settings(path)
+
+
+def validate_limit(limit: int) -> int:
+    if not (MIN_LIMIT <= limit <= MAX_LIMIT):
+        raise ConfigurationError(f"limit must be between {MIN_LIMIT} and {MAX_LIMIT}, got {limit}.")
+    return limit

surfx/errors.py

@@ -0,0 +1,64 @@
+"""Custom exceptions used across Surfx.
+
+All exceptions carry a short, user-facing ``message`` that is safe to print
+directly to the terminal without leaking internals such as stack traces or
+credential values.
+"""
+
+from __future__ import annotations
+
+
+class SurfxError(Exception):
+    """Base class for all Surfx errors."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class ConfigurationError(SurfxError):
+    """Raised when Surfx or a provider is misconfigured."""
+
+
+class ProviderNotFoundError(SurfxError):
+    """Raised when the requested provider name is unknown."""
+
+
+class ProviderNotConfiguredError(ConfigurationError):
+    """Raised when a provider is missing required configuration (a URL, key, etc.)."""
+
+
+class AuthenticationError(SurfxError):
+    """Raised when a provider rejects the supplied credentials."""
+
+
+class QuotaExceededError(SurfxError):
+    """Raised when a provider's usage quota has been exhausted."""
+
+
+class RateLimitedError(SurfxError):
+    """Raised when a provider is throttling requests."""
+
+
+class NetworkError(SurfxError):
+    """Raised for connectivity problems: DNS failures, unreachable hosts, etc."""
+
+
+class TimeoutError_(SurfxError):  # noqa: N818 - avoid shadowing builtins.TimeoutError
+    """Raised when a request exceeds its configured timeout."""
+
+
+class MalformedResponseError(SurfxError):
+    """Raised when a provider returns a response Surfx cannot parse."""
+
+
+class EmptyResultsError(SurfxError):
+    """Raised when a search completes successfully but returns no results."""
+
+
+class InvalidLimitError(SurfxError):
+    """Raised when a requested result limit is out of the allowed range."""
+
+
+class CacheError(SurfxError):
+    """Raised for cache read/write problems. Never fatal to the CLI."""