Python SDK | Stophy

Install

pip install stophy

It needs Python 3.9 or newer.

Authenticate

api_key defaults to the STOPHY_API_KEY environment variable, so a bare Stophy() picks it up.

import os

from stophy import Stophy

stophy = Stophy(api_key=os.environ["STOPHY_API_KEY"])

Without a key, web search, YouTube search and YouTube transcripts still work:

from stophy import Stophy

result = Stophy().web.search(query="bun runtime")
print(result["data"]["results"])

Every other endpoint raises StophyError with code unauthorized and status 401 when called without a key.

Make a call

import os

from stophy import Stophy

stophy = Stophy(api_key=os.environ["STOPHY_API_KEY"])

posts = stophy.reddit.search(query="bun runtime", limit=10)
print(posts["data"], posts["creditsUsed"])

replies = stophy.youtube.comments.replies(video="dQw4w9WgXcQ", cursor="...")
print(replies["data"])

Responses are plain dictionaries shaped like the API reference. Methods follow the endpoint id, with keyword arguments in snake_case. Nested ids are nested attributes: youtube.comments.replies is stophy.youtube.comments.replies(...). A JSON field named from is passed as from_.

Get markdown

Pass format="markdown" to get a string:

from stophy import Stophy

with Stophy() as stophy:
    page = stophy.youtube.search(query="rust tutorial", limit=2, format="markdown")
    print(page)

Async

AsyncStophy has the same methods. Await them.

import asyncio

from stophy import AsyncStophy


async def main() -> None:
    async with AsyncStophy() as stophy:
        result = await stophy.web.search(query="bun runtime", limit=3)
        for item in result["data"]["results"]:
            print(item["title"])


asyncio.run(main())

Paging

import os

from stophy import Stophy

stophy = Stophy(api_key=os.environ["STOPHY_API_KEY"])
cursor = None
while True:
    page = stophy.reddit.search(query="bun runtime", cursor=cursor)
    print(page["data"])
    cursor = page["data"].get("cursor")
    if not cursor:
        break

Handle errors and retries

from stophy import Stophy, StophyError

stophy = Stophy()

try:
    stophy.reddit.search(query="bun runtime")
except StophyError as error:
    print(error.status, error.code, str(error))
    print(error.retryable, error.retry_after_seconds, error.request_id)

StophyError has status, code, retryable, retry_after_seconds and request_id. The message is str(error). See Errors for every code. The SDK retries network errors and 429/5xx responses on its own, honoring Retry-After, before it raises. Set max_retries=0 to turn that off. StophyError only reaches your code after retries are exhausted.

Options

import os

from stophy import Stophy

stophy = Stophy(
    api_key=os.environ["STOPHY_API_KEY"],
    timeout=20.0,
    max_retries=3,
    retry_initial_delay=0.5,
    headers={"x-app": "my-app"},
)

Option	Default	What it does
`api_key`	`STOPHY_API_KEY`	Your API key. Leave it unset to use the free endpoints.
`base_url`	`STOPHY_BASE_URL` or `https://api.stophy.dev`	Where requests go
`timeout`	`30.0`	Timeout in seconds
`max_retries`	`2`	Retries for network errors and `429`/`5xx`. `0` turns them off.
`retry_initial_delay`	`0.5`	Base backoff delay in seconds. Each retry waits longer than the last.
`headers`	none	Extra headers on every request
`transport`	none	An `httpx` transport, for tests

Use the client as a context manager, or call close() when you are done.

Usage and logs

These need an API key.

import os

from stophy import Stophy

stophy = Stophy(api_key=os.environ["STOPHY_API_KEY"])

usage = stophy.usage()
print(usage["balanceMicros"], usage["creditsUsed"], usage["requestCount"])

logs = stophy.logs(days=7, page=0, endpoint="web.search")
for entry in logs["logs"]:
    print(entry["createdAt"], entry["endpoint"], entry["credits"])

balanceMicros is your balance in millionths of a dollar: 1000000 is $1.

​Install

​Authenticate

​Make a call

​Get markdown

​Async

​Paging

​Handle errors and retries

​Options

​Usage and logs