block_detector

Detect Google Scholar’s soft blocks.

Scholar rarely answers with a clean error. From a flagged client it redirects to a JavaScript “Verifying…” page (/sgsync) or to the Google sign-in page, both with HTTP 200, so scholarly parses them and silently finds zero results. This module watches the final URL of every Scholar response and remembers a block for a cooldown period, so callers can fail fast instead of retrying into the wall.

google_scholar_search_mcp.block_detector.classify(response)[source]

Say whether a response is a block page.

Parameters:

response (httpx.Response) – Final response, after redirects.

Returns:

str | None – Human-readable reason, or None for a normal response.

Return type:

str | None

class google_scholar_search_mcp.block_detector.BlockDetector(cooldown_seconds=900.0)[source]

Bases: object

Track whether Scholar is currently blocking this client.

reset()[source]

Forget the block seen during the previous call.

property reason: str | None

Reason of a block seen since the last reset(), if any.

trip()[source]

Start the cooldown after a confirmed block.

cooldown_remaining()[source]

Seconds left until Scholar should be tried again.

Returns:

float – 0.0 when Scholar may be tried.

Return type:

float