bytekit-sdk

Official Python SDK for the ByteKit API.

The PyPI distribution is bytekit-sdk; the import name is bytekit.

Generated from the OpenAPI spec using openapi-python-client, filtered to the stable v0.1 operations.

Installation

pip install bytekit-sdk

Quick start

from bytekit import AuthenticatedClient
from bytekit.api.scrape import create_scrape
from bytekit.errors import UnexpectedStatus
from bytekit.models.scrape_request import ScrapeRequest

# base_url defaults to https://api.bytekit.com, so only the token is required.
client = AuthenticatedClient(token="sk_live_your_api_key_here")

body = ScrapeRequest(url="https://example.com")

try:
    response = create_scrape.sync(client=client, body=body)
    # response.formats.markdown is str | Unset — only present when "markdown" was requested
    print(response.formats.markdown)
except UnexpectedStatus as err:
    # Errors now raise loudly by default instead of returning None.
    print(f"request failed with status {err.status_code}: {err.code} {err.message}")

Defaults

The client ships with production-ready defaults so AuthenticatedClient(token=...) works out of the box:

Explicit constructor arguments always win over these defaults (explicit arg > default).

Async usage

import asyncio
from bytekit import AuthenticatedClient
from bytekit.api.screenshots import create_screenshot
from bytekit.models.screenshot_request import ScreenshotRequest

async def main():
    client = AuthenticatedClient(token="sk_live_your_api_key_here")
    body = ScreenshotRequest(url="https://example.com")
    response = await create_screenshot.asyncio(client=client, body=body)
    print(response)

asyncio.run(main())

Available operations

Regenerating

To regenerate the client after API changes:

pnpm --filter @bytekit/sdk-python generate

This runs scripts/filter-spec.ts to produce filtered-openapi.yaml (filtered to v0.1 operations), runs scripts/prune-stale-api.py to delete any src/bytekit/api/<tag>/ directory the filtered spec no longer produces (generate --overwrite itself already rebuilds api/ from scratch on every run, so this step is defense-in-depth for a standalone run of the prune script or a future generator version — the path that actually needs the guard is pnpm generate:docs, which enumerates api/ on disk independent of generate and can otherwise resurrect a tag whose tracked files were git rm-ed but whose untracked __pycache__/ survives; see scripts/prune-stale-api.py's module docstring and has_operations() in scripts/generate-docs.py), invokes openapi-python-client generate to update src/bytekit/, then runs scripts/inject-handwritten.py to re-append hand-written fragments (e.g. the AuthenticatedClient.search() convenience method) from scripts/hand_written/ and re-patch the generated client.py/errors.py with the runtime defaults and error enrichment described above — because --overwrite overwrites every file it emits, both the hand-written code and these patches are wiped on every regen and must be re-applied afterward.

Development

# Run tests
cd packages/sdk-python
python3 -m pytest tests/ -v

Publishing

PyPI publish is handled in #2226 — .woodpecker/publish.yaml's publish-pypi step, version-gated the same way as the npm siblings (publishes only when the local pyproject.toml version differs from what's live on PyPI).

bytekit-sdk has never been published. Before the commit that arms packages/sdk-python/pyproject.toml in publish.yaml's workflow-level when.path.include is promoted from staging to main, an operator MUST publish 0.3.0 to PyPI manually and under supervision. Reason: bytekit-sdk 404s on PyPI today, so the automatic version-compare gate's || echo "0.0.0" fallback always fires — the first time that arming reaches main, it would trigger a real, irreversible first twine upload with no manual confirmation step in between. Once the manual first release exists, PUBLISHED == CURRENT and every later automatic run at an unchanged version is a no-op, same as the npm packages. See the comment at the armed when.path.include entry in .woodpecker/publish.yaml for the mechanism.