bytekit-sdk 0.3.0__tar.gz → 0.3.4__tar.gz

{bytekit_sdk-0.3.0 → bytekit_sdk-0.3.4}/.gitignore

@@ -47,6 +47,14 @@ packages/http-fetcher/server
 packages/http-fetcher/browserforge-bench
 __pycache__/
 *.pyc
+# ruff's incremental cache. Written by the openapi-python-client post-hooks INSIDE the
+# generated output dir (packages/sdk-python/src/bytekit/.ruff_cache/). ruff already drops a
+# self-ignoring `.gitignore` containing `*` in there, which is exactly why the directory went
+# unnoticed for so long — `git status` never mentions it. This entry is belt-and-braces so the
+# by-product is ignored even if ruff stops self-ignoring. The reproducibility gate
+# (ci/scripts/check-sdk-python-regen.sh) excludes it from BOTH of its diffs: cache entry names
+# are hashes of the absolute path, so two clean-room generates differ by construction.
+.ruff_cache/
 # Generated artifact — reproduced via `pnpm --filter @rapidcrawl/sdk-python generate`
 packages/sdk-python/filtered-openapi.yaml
 # NOTE: the MCP server's generated docs JSON (see packages/mcp-server/src) is intentionally

bytekit_sdk-0.3.4/CHANGELOG.md

@@ -0,0 +1,192 @@
+# Changelog
+
+All notable changes to the ByteKit Python SDK are documented here.
+PyPI distribution: `bytekit-sdk`. Import name: `bytekit`.
+
+## 0.3.4
+
+### Breaking
+
+- **`CreateBulkBody`, `CreateBulkBodyDefaults`, `CreateBulkBodyItemsItem`, and
+  `CreateFetchBulkBodyUrlsItemType1` lost their additional-properties mapping API.**
+  `docs/api/openapi.yaml`'s `/v1/bulk` request schema declares `additionalProperties: false`
+  on the top-level body, `items[]`, and `defaults` (issue #2641), and `/v1/fetch/bulk`'s
+  per-item override schema inside `urls[]` declares the same (issue #2648), matching the
+  gateway's own `.strict()` validators. The code generator responds to
+  `additionalProperties: false` by omitting the catch-all mapping it otherwise attaches to
+  every generated model, so these four models no longer expose `additional_properties`, the
+  `additional_keys` property, `__getitem__`, `__setitem__`, `__delitem__`, or `__contains__`.
+  Code that did `body["some_key"] = value`, `"some_key" in body`, or read
+  `body.additional_keys` on any of these four models will now raise
+  `AttributeError`/`TypeError` instead. Use the model's declared `attrs` fields directly
+  instead (e.g. `CreateBulkBodyItemsItem(url=..., type=...)`,
+  `CreateFetchBulkBodyUrlsItemType1(url=..., format_=...)`); the server itself now rejects
+  unrecognized keys on these endpoints with `422 validation_error`, so the removed escape
+  hatch could never have reached the API successfully anyway. This is scoped to the four
+  `create_bulk_body*` / `create_fetch_bulk_body_urls_item_type_1` models — no other generated
+  model is affected.
+
+## 0.3.3
+
+### Security
+
+- **Path parameters are now percent-encoded.** All 13 operations that interpolate an id into
+  their URL (`get_scrape`, `get_screenshot`, `get_bulk`, `delete_bulk`,
+  `list_bulk_screenshots`, `get_scrape_bulk`, `get_fetch_bulk`, `get_monitor`,
+  `update_monitor`, `delete_monitor`, `list_monitor_captures`, `get_sitemap`,
+  `retry_webhook_delivery`) previously interpolated the value raw, so an id containing `/`,
+  `?`, `#` or traversal segments could retarget the request to a **different path on the same
+  authenticated host** — e.g. a `DELETE /v1/bulk/{id}` becoming a delete against another
+  resource. Values are now encoded with `quote(str(value), safe="")`. This is **not** a
+  breaking change for any id the API issues: hex and `sc_`/`ss_`/`mon_`/`sm_`/`bulk_`-prefixed
+  ids contain no reserved characters, so the resulting URL is byte-identical to before.
+  No id-format validation was added — the client does not reject id shapes.
+
+### Fixed
+
+- **Reusing one client across several `asyncio.run(...)` calls no longer raises
+  `RuntimeError: Event loop is closed`.** An `httpx.AsyncClient`'s connection pool belongs to
+  the event loop that created it, and the SDK cached its internal async client
+  unconditionally. It now tracks which loop that client was built on and transparently
+  rebuilds it when the running loop changes, re-applying `base_url`, headers, timeout,
+  `httpx_args` and authentication. Behavior is unchanged when no loop is running, and a client
+  you supply via `set_async_httpx_client(...)` is **never** rebuilt or closed — it stays yours
+  to manage. See the README's new "Clients and event loops" section.
+- **The README quick start now prints markdown instead of an `Unset` placeholder.** It
+  requested no `formats`, so the server applied its `raw_html` default and
+  `result.formats.markdown` was legitimately unset. It now asks for
+  `formats=[ScrapeRequestFormatsItem.MARKDOWN]` — note `formats` takes enum members, not plain
+  strings.
+- **`client.search(type="images")` no longer crashes with a bare `KeyError: 'snippet'`.**
+  The OpenAPI spec's search result-item schema declared `snippet` as `required` while its
+  own description said the key is omitted for `images` results — a self-contradiction the
+  code generator trusted literally, so `CreateSearchResponse200ResultsItem.from_dict`
+  unconditionally did `d.pop("snippet")`. `snippet` (like `date`) is now `Union[Unset, str]`,
+  matching the real gateway behavior (`web`/`news` results still always carry `snippet`;
+  `images` results omit it entirely) — fixed at the spec level (`docs/api/openapi.yaml`) and
+  regenerated, not patched in the generated model. (Issue #2579.)
+- **Server defaults are no longer materialized into request wire bodies/query strings
+  for inline request bodies and `$ref`'d parameters.** `scripts/filter-spec.ts`'s
+  default-stripping traversal previously only followed `$ref`'d request-body component
+  schemas, so `ScrapeRequest`/`FetchRequest` were clean but every other request-direction
+  shape kept baking in server defaults: `/v1/search`'s fully-inline body (`type`,
+  `limit`, `country`, `language`, `date_range`), all three bulk endpoints' bodies and
+  their nested `Defaults`/`ItemsItem` models, and `$ref`'d query parameters
+  (`GET /v1/fetch`'s `country`/`timeout_ms`/`cache_ttl`, `list_monitors`'
+  `limit`/`status`, `list_webhook_deliveries`'/`list_monitor_captures`' `limit`,
+  `create_screenshot`'s `async`). The traversal now walks inline request bodies AND
+  parameters (both operation-level and shared path-item-level, `$ref`'d or inline)
+  before generation, so an omitted optional field always serializes to nothing and
+  the server's own default applies — caller-supplied values are unaffected and still
+  serialize exactly as given (issue #2592).
+- `tests/test_no_materialized_defaults.py` rewritten to enumerate every
+  request-direction model and operation parameter programmatically (walking the
+  generated `bytekit.api`/`bytekit.models` trees) instead of sampling two known-clean
+  models, so a newly introduced leaker is caught automatically.
+
+### Changed
+
+- **The source distribution no longer ships `tests/`.** The bundled suite could not be
+  collected from an unpacked sdist: 12 of its 27 modules require the repository's codegen
+  scripts or the canonical OpenAPI spec, neither of which belongs in a published
+  distribution, and three of them build distributions of the package itself. Nothing
+  importable was removed — the **wheel is unchanged**, `py.typed` included, so
+  `pip install bytekit-sdk` is unaffected.
+
+### Internal
+
+- CI now proves the committed client is reproducible from the canonical OpenAPI spec, and that
+  the generation chain is deterministic (generating twice yields byte-identical output). This
+  closes the gap where a spec change could land with a TypeScript-only regeneration and leave
+  the Python client silently stranded on an older spec.
+- `ruff` is now pinned to an exact version alongside the code generator. The generator runs
+  `ruff` over everything it emits, so it — not the generator alone — determines the committed
+  bytes; the generator itself accepts any `ruff<0.13`, which meant a fresh install could
+  reformat the whole tree. Bumping the pin is a deliberate, reviewed reformat.
+- The PEP 561 `py.typed` marker is now emitted by the post-generation injector rather than
+  hand-maintained inside the generated tree (the generator omits it under `--meta none`).
+
+## 0.3.2
+
+### Added
+
+- **`bytekit.__version__`** reports the installed distribution version, resolved at import
+  time from `importlib.metadata` (so it can never drift from `pyproject.toml`'s
+  `[project].version`). When the package is imported from a source tree with no installed
+  distribution it reads `0.0.0.dev0` rather than raising. The dead version override in
+  `sdk-python-config.yaml` — inert under `--meta none` and contradicting the real
+  version — has been removed, leaving one authoritative version.
+
+### Fixed
+
+- **`AuthenticatedClient.search()` is now visible to type checkers.** It was attached to the
+  class after creation, so despite the package shipping a `py.typed` marker, `mypy` and
+  `pyright` reported `"AuthenticatedClient" has no attribute "search"`. It is now declared as a
+  real method in the class body that delegates to the same implementation: **runtime behavior,
+  arguments, return type and raised errors are unchanged** — only the static surface is fixed.
+
+## 0.3.1
+
+### Fixed
+
+- **The "never a bare `json.JSONDecodeError`" guarantee is now package-wide across all
+  generated operations**, not only the `AuthenticatedClient.search()` wrapper. Every
+  generated operation previously called `response.json()` unconditionally on a
+  DOCUMENTED status, so a `500`/`502` serving an HTML load-balancer page raised a bare
+  `json.JSONDecodeError` from inside the SDK. All operations now parse documented
+  statuses through a shared guard: a non-JSON body raises the typed
+  `errors.UnexpectedStatus` (or returns `None` when
+  `raise_on_unexpected_status=False`), carrying the status code and the raw body.
+- **`errors.UnexpectedStatus.code` / `.message` are now populated for generated
+  operations too**, from the documented `Error` envelope — previously they were always
+  `None` outside `search()`. A string-valued `error` (the masked search-provider `502`)
+  still never enriches, so the upstream provider's identity is never surfaced.
+- Behavior on JSON bodies is unchanged: JSON success bodies still parse into their typed
+  success models, documented JSON error bodies are still **returned** as typed `Error`
+  models rather than raised, and `raise_on_unexpected_status` semantics are untouched.
+  The documented non-JSON success paths — `get_fetch`/`post_fetch`'s raw-text `200` and
+  `delete_monitor`'s empty `204` — are likewise unaffected.
+- **README error documentation corrected.** The quick-start example wrapped a call in
+  `try/except UnexpectedStatus` and then read `response.formats.markdown`, but a
+  documented `4xx` _returns_ a typed `Error` model without raising — so the documented
+  example failed with `AttributeError: 'Error' object has no attribute 'formats'`. The
+  README now documents the real two-tier contract, and the snippet is executed by
+  `tests/test_readme_examples.py` so it cannot silently drift again.
+
+### Documentation
+
+- Removed the contributor-only `Publishing`, `Regenerating`, and `Development` sections
+  from the published README (the PyPI long description) — they described internal CI
+  mechanics and a monorepo-contributor workflow that do not belong on a public package
+  index. The regeneration/development knowledge is preserved in-repo in
+  `packages/sdk-python/CLAUDE.md` (not shipped in the distribution).
+- Added a `## License` section and a `LICENSE` file, matching the npm sibling packages.
+
+## 0.3.0
+
+### Breaking
+
+- **PyPI distribution renamed `bytekit` -> `bytekit-sdk`.** PyPI administratively
+  denylists the bare name `bytekit`, so the package installs as
+  `pip install bytekit-sdk`. The **import name is unchanged** — `import bytekit`
+  still works, and no module path moved. Nothing was ever published under the old
+  distribution name, so there is no migration for existing installs.
+- **`raise_on_unexpected_status` now defaults to `True`.** Undocumented response
+  statuses now raise `errors.UnexpectedStatus` instead of silently returning `None`.
+  Callers that relied on the old `None`-return behavior must pass
+  `raise_on_unexpected_status=False` explicitly to opt out.
+- **`base_url` is now a keyword-only argument.** It gained a default
+  (`https://api.bytekit.com`), and to satisfy attrs field ordering it became
+  keyword-only. Any caller passing `base_url` positionally must switch to the
+  `base_url=` keyword form. (`base_url=` was already the documented usage.)
+
+### Added
+
+- `AuthenticatedClient(token=...)` now works out of the box against production:
+  `base_url` defaults to `https://api.bytekit.com`.
+- Finite default request timeout of `120s` (`httpx.Timeout(120.0)`) — requests no
+  longer hang indefinitely. Override with `timeout=`.
+- `errors.UnexpectedStatus` now carries optional `.code` / `.message` attributes.
+  The `AuthenticatedClient.search()` wrapper populates them from the documented
+  `Error` envelope, and safely raises a typed error (never a bare
+  `json.JSONDecodeError`) on a non-JSON documented-status body such as an HTML 502.

bytekit_sdk-0.3.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hunt Labs, Inc.
+
+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.

{bytekit_sdk-0.3.0 → bytekit_sdk-0.3.4}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: bytekit-sdk
-Version: 0.3.0
+Version: 0.3.4
 Summary: Official Python SDK for the ByteKit API
 Project-URL: Homepage, https://bytekit.com
 Project-URL: Repository, https://github.com/Hunt-Labs-Inc/ByteKit
 Project-URL: Documentation, https://bytekit.com/docs
 License-Expression: MIT
+License-File: LICENSE
 Keywords: api,bytekit,crawler,llm,markdown,scraping,screenshots,sdk,web-scraping
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -37,26 +38,72 @@ Generated from the OpenAPI spec using [openapi-python-client](https://github.com
 pip install bytekit-sdk
 ```
 
+The installed version is available as `bytekit.__version__`.
+
 ## Quick start
 
 ```python
 from bytekit import AuthenticatedClient
 from bytekit.api.scrape import create_scrape
-from bytekit.errors import UnexpectedStatus
 from bytekit.models.scrape_request import ScrapeRequest
+from bytekit.models.scrape_request_formats_item import ScrapeRequestFormatsItem
+from bytekit.models.scrape_success_envelope import ScrapeSuccessEnvelope
 
 # 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")
+result = create_scrape.sync(
+    client=client,
+    body=ScrapeRequest(
+        url="https://example.com",
+        # Ask for markdown explicitly. `formats` is a list of enum members, not plain
+        # strings. Omit it and the server returns raw HTML instead, leaving
+        # `formats.markdown` unset.
+        formats=[ScrapeRequestFormatsItem.MARKDOWN],
+    ),
+)
+
+if isinstance(result, ScrapeSuccessEnvelope):
+    print(result.formats.markdown)
+```
+
+See [Error handling](#error-handling) for what `result` can be when the request fails.
+
+### Error handling
+
+The SDK has a **two-tier** error contract. Both tiers are safe: an operation never raises
+a bare `json.JSONDecodeError`, even when a server returns an HTML error page.
+
+| Situation                                                                                                                   | What you get                                                                                                                                                                       |
+| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A status the OpenAPI spec **documents** for that operation (e.g. a `422` or `500` on `create_scrape`), with a JSON body     | The typed `Error` model is **returned**, not raised. Check with `isinstance(result, Error)` and read `result.error.code` / `result.error.message`.                                 |
+| An **undocumented** status, or a **non-JSON body on a documented status** (HTML error page, load-balancer text, empty body) | `errors.UnexpectedStatus` is **raised**, carrying `.status_code` and the raw `.content`. When the body is the documented `Error` envelope, `.code` / `.message` are populated too. |
+| Either of the above, with `raise_on_unexpected_status=False`                                                                | Nothing is raised; the operation returns `None`.                                                                                                                                   |
+
+```python
+from bytekit import AuthenticatedClient
+from bytekit.api.scrape import create_scrape
+from bytekit.errors import UnexpectedStatus
+from bytekit.models.error import Error
+from bytekit.models.scrape_request import ScrapeRequest
+from bytekit.models.scrape_success_envelope import ScrapeSuccessEnvelope
+
+client = AuthenticatedClient(token="sk_live_your_api_key_here")
 
 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)
+    result = create_scrape.sync(client=client, body=ScrapeRequest(url="https://example.com"))
 except UnexpectedStatus as err:
-    # Errors now raise loudly by default instead of returning None.
+    # Undocumented status, or a non-JSON body on a documented one. Never a JSONDecodeError.
     print(f"request failed with status {err.status_code}: {err.code} {err.message}")
+else:
+    if isinstance(result, Error):
+        # Documented 4xx/5xx with a JSON body: RETURNED as a typed model, not raised.
+        print(f"api error {result.error.code}: {result.error.message}")
+    elif isinstance(result, ScrapeSuccessEnvelope):
+        print(result.formats.markdown)
+    else:
+        # 202 ScrapeQueuedEnvelope — poll get_scrape with this id until it completes.
+        print(f"queued as {result.id}")
 ```
 
 ### Defaults
@@ -88,6 +135,29 @@ async def main():
 asyncio.run(main())
 ```
 
+### Clients and event loops
+
+An `httpx.AsyncClient` — and therefore its connection pool — belongs to the event loop that
+created it. The recommended shape is a context manager, which scopes the client to exactly one
+loop:
+
+```python
+async def main():
+    async with AuthenticatedClient(token="sk_live_your_api_key_here") as client:
+        ...
+```
+
+Two rules cover everything else:
+
+- **A client the SDK builds for you is rebuilt automatically.** If you reuse one client across
+  several `asyncio.run(...)` calls, the SDK notices the running loop has changed and transparently
+  replaces its internal `AsyncClient`. Your `base_url`, headers, timeout, `httpx_args` and
+  authentication are all re-applied, so this is invisible apart from a new connection. Calling
+  `get_async_httpx_client()` outside any running loop returns the cached client unchanged.
+- **A client you pass to `set_async_httpx_client(...)` is yours.** The SDK never rebuilds or
+  closes it, so a client you supply must be created and used on the same loop — that is the one
+  case where crossing loops is still your responsibility.
+
 ## Available operations
 
 | Module            | Method                                                                                                        | Description                                |
@@ -105,37 +175,6 @@ asyncio.run(main())
 | `api.webhooks`    | `list_webhook_deliveries`, `retry_webhook_delivery`                                                           | Webhook delivery log & retry               |
 | `api.account`     | `get_account`                                                                                                 | Account details                            |
 
-## Regenerating
-
-To regenerate the client after API changes:
-
-```bash
-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
-
-```bash
-# Run tests
-cd packages/sdk-python
-python3 -m pytest tests/ -v
-```
+## License
 
-## Publishing
-
-PyPI publish is handled in [#2226](https://github.com/Hunt-Labs-Inc/ByteKit/issues/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.
+MIT — see [LICENSE](./LICENSE).

{bytekit_sdk-0.3.0 → bytekit_sdk-0.3.4}/README.md

@@ -12,26 +12,72 @@ Generated from the OpenAPI spec using [openapi-python-client](https://github.com
 pip install bytekit-sdk
 ```
 
+The installed version is available as `bytekit.__version__`.
+
 ## Quick start
 
 ```python
 from bytekit import AuthenticatedClient
 from bytekit.api.scrape import create_scrape
-from bytekit.errors import UnexpectedStatus
 from bytekit.models.scrape_request import ScrapeRequest
+from bytekit.models.scrape_request_formats_item import ScrapeRequestFormatsItem
+from bytekit.models.scrape_success_envelope import ScrapeSuccessEnvelope
 
 # 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")
+result = create_scrape.sync(
+    client=client,
+    body=ScrapeRequest(
+        url="https://example.com",
+        # Ask for markdown explicitly. `formats` is a list of enum members, not plain
+        # strings. Omit it and the server returns raw HTML instead, leaving
+        # `formats.markdown` unset.
+        formats=[ScrapeRequestFormatsItem.MARKDOWN],
+    ),
+)
+
+if isinstance(result, ScrapeSuccessEnvelope):
+    print(result.formats.markdown)
+```
+
+See [Error handling](#error-handling) for what `result` can be when the request fails.
+
+### Error handling
+
+The SDK has a **two-tier** error contract. Both tiers are safe: an operation never raises
+a bare `json.JSONDecodeError`, even when a server returns an HTML error page.
+
+| Situation                                                                                                                   | What you get                                                                                                                                                                       |
+| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A status the OpenAPI spec **documents** for that operation (e.g. a `422` or `500` on `create_scrape`), with a JSON body     | The typed `Error` model is **returned**, not raised. Check with `isinstance(result, Error)` and read `result.error.code` / `result.error.message`.                                 |
+| An **undocumented** status, or a **non-JSON body on a documented status** (HTML error page, load-balancer text, empty body) | `errors.UnexpectedStatus` is **raised**, carrying `.status_code` and the raw `.content`. When the body is the documented `Error` envelope, `.code` / `.message` are populated too. |
+| Either of the above, with `raise_on_unexpected_status=False`                                                                | Nothing is raised; the operation returns `None`.                                                                                                                                   |
+
+```python
+from bytekit import AuthenticatedClient
+from bytekit.api.scrape import create_scrape
+from bytekit.errors import UnexpectedStatus
+from bytekit.models.error import Error
+from bytekit.models.scrape_request import ScrapeRequest
+from bytekit.models.scrape_success_envelope import ScrapeSuccessEnvelope
+
+client = AuthenticatedClient(token="sk_live_your_api_key_here")
 
 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)
+    result = create_scrape.sync(client=client, body=ScrapeRequest(url="https://example.com"))
 except UnexpectedStatus as err:
-    # Errors now raise loudly by default instead of returning None.
+    # Undocumented status, or a non-JSON body on a documented one. Never a JSONDecodeError.
     print(f"request failed with status {err.status_code}: {err.code} {err.message}")
+else:
+    if isinstance(result, Error):
+        # Documented 4xx/5xx with a JSON body: RETURNED as a typed model, not raised.
+        print(f"api error {result.error.code}: {result.error.message}")
+    elif isinstance(result, ScrapeSuccessEnvelope):
+        print(result.formats.markdown)
+    else:
+        # 202 ScrapeQueuedEnvelope — poll get_scrape with this id until it completes.
+        print(f"queued as {result.id}")
 ```
 
 ### Defaults
@@ -63,6 +109,29 @@ async def main():
 asyncio.run(main())
 ```
 
+### Clients and event loops
+
+An `httpx.AsyncClient` — and therefore its connection pool — belongs to the event loop that
+created it. The recommended shape is a context manager, which scopes the client to exactly one
+loop:
+
+```python
+async def main():
+    async with AuthenticatedClient(token="sk_live_your_api_key_here") as client:
+        ...
+```
+
+Two rules cover everything else:
+
+- **A client the SDK builds for you is rebuilt automatically.** If you reuse one client across
+  several `asyncio.run(...)` calls, the SDK notices the running loop has changed and transparently
+  replaces its internal `AsyncClient`. Your `base_url`, headers, timeout, `httpx_args` and
+  authentication are all re-applied, so this is invisible apart from a new connection. Calling
+  `get_async_httpx_client()` outside any running loop returns the cached client unchanged.
+- **A client you pass to `set_async_httpx_client(...)` is yours.** The SDK never rebuilds or
+  closes it, so a client you supply must be created and used on the same loop — that is the one
+  case where crossing loops is still your responsibility.
+
 ## Available operations
 
 | Module            | Method                                                                                                        | Description                                |
@@ -80,37 +149,6 @@ asyncio.run(main())
 | `api.webhooks`    | `list_webhook_deliveries`, `retry_webhook_delivery`                                                           | Webhook delivery log & retry               |
 | `api.account`     | `get_account`                                                                                                 | Account details                            |
 
-## Regenerating
-
-To regenerate the client after API changes:
-
-```bash
-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
-
-```bash
-# Run tests
-cd packages/sdk-python
-python3 -m pytest tests/ -v
-```
+## License
 
-## Publishing
-
-PyPI publish is handled in [#2226](https://github.com/Hunt-Labs-Inc/ByteKit/issues/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.
+MIT — see [LICENSE](./LICENSE).

{bytekit_sdk-0.3.0 → bytekit_sdk-0.3.4}/pyproject.toml

@@ -7,7 +7,7 @@
 # `pip install bytekit-sdk` yields a working `import bytekit`. Mirrors the npm sibling
 # @hunt-labs/bytekit-sdk.
 name = "bytekit-sdk"
-version = "0.3.0"
+version = "0.3.4"
 description = "Official Python SDK for the ByteKit API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -57,6 +57,22 @@ Documentation = "https://bytekit.com/docs"
 [dependency-groups]
 dev = [
     "openapi-python-client==0.25.3",
+    # THE FORMATTER IS PART OF THE CODEGEN CONTRACT (#2593). openapi-python-client's DEFAULT
+    # post_hooks are `ruff check . --fix --extend-select=I` and `ruff format .`, run with
+    # cwd = --output-path (see openapi_python_client/config.py) — and sdk-python-config.yaml
+    # sets no `post_hooks` override, so they apply. ruff therefore decides the BYTES of every
+    # emitted module, which makes pinning the generator alone insufficient.
+    #
+    # The generator's own metadata only asks for `ruff<0.13,>=0.2`, so a fresh
+    # `pip install openapi-python-client==0.25.3` resolves 0.12.x — nine minor versions above
+    # the version that actually produced the committed tree. Left unpinned, the reproducibility
+    # gate (ci/scripts/check-sdk-python-regen.sh) would red a CORRECT tree, and no regen would
+    # stably fix it. 0.3.7 is measured to reproduce all 221 committed modules byte-for-byte.
+    #
+    # Bumping this pin is a DELIBERATE, REVIEWED 221-file reformat — exactly like bumping the
+    # generator pin above — never an incidental upgrade. The gate reads this pin, so there is
+    # no second copy of the version to keep in sync.
+    "ruff==0.3.7",
     # Read by scripts/prune-stale-api.py (parses filtered-openapi.yaml to derive which
     # api/ group dirs the spec still produces) and by tests/conftest.py. Generation-time
     # and test-time only — never a runtime dependency of the published client.
@@ -82,11 +98,26 @@ testpaths = ["tests"]
 pythonpath = ["src"]
 
 [tool.hatch.build.targets.sdist]
+# The test tree was REMOVED from this allowlist in #2593 (the pre-merge grep gate asserts the
+# glob appears zero times in this file, so a reintroduction is caught even inside a comment —
+# hence the prose here names it in words). The shipped suite could not collect: 12 of 27 modules need
+# `scripts/` (contributor-only codegen tooling) or the canonical `docs/api/openapi.yaml` (which
+# lives two directories above this package), and three of them build distributions of this
+# package — incoherent from inside an unpacked sdist. Verified from the built artifact:
+# `FileNotFoundError: .../scripts/inject-handwritten.py` interrupted collection.
+#
+# Dropped rather than made self-contained: vendoring `scripts/` + a copy of the spec into a
+# public distribution would breach the same published-content boundary that keeps CLAUDE.md out.
+# A test tree that cannot run is worse than none — it reads as a promise to downstream packagers
+# that running it validates the install. Pinned by tests/test_sdist_excludes_tests.
+#
+# The WHEEL is untouched (see [tool.hatch.build.targets.wheel] above): no importable module is
+# removed from what users install.
 include = [
     "src/bytekit/**",
-    "tests/**",
     "README.md",
     "CHANGELOG.md",
+    "LICENSE",
 ]
 exclude = [
     "node_modules",

bytekit_sdk-0.3.4/src/bytekit/__init__.py

@@ -0,0 +1,39 @@
+"""A client library for accessing ByteKit API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)
+
+
+# BYTEKIT-HANDWRITTEN: __version__ (injected post-generation)
+#
+# This fragment is APPENDED to the generated src/bytekit/__init__.py by
+# scripts/inject-handwritten.py after every regeneration. It lives here (outside
+# src/bytekit/) so `openapi-python-client generate --overwrite`, which deletes and
+# recreates the entire src/bytekit/ package, can never delete it.
+#
+# ONE AUTHORITATIVE VERSION (#2549). The value is RESOLVED, never restated: it comes from the
+# installed distribution's metadata, which IS pyproject.toml's `[project].version` once the
+# distribution is built or installed. There is nothing here to keep in sync and nothing that can
+# drift — which is the whole point, since the dead generator-config version override this
+# replaced (inert under `--meta none`) had silently contradicted the real version.
+#
+# Note the DISTRIBUTION name is `bytekit-sdk` while the IMPORT name is `bytekit` (#2530): PyPI
+# administratively denylists the bare name. `importlib.metadata.version` takes the DISTRIBUTION.
+#
+# `__all__` is deliberately NOT extended: dunder module attributes are conventionally excluded
+# from it, and this fragment is appended AFTER the generated `__all__` tuple, so mutating it
+# would require a patch rather than an append.
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+try:
+    __version__ = _dist_version("bytekit-sdk")
+except PackageNotFoundError:
+    # Imported from a source tree with no installed distribution — the default for this repo's
+    # own test suite, which runs install-free via pyproject.toml's `pythonpath = ["src"]`.
+    # A valid PEP 440 development version, never an empty string and never an import-time raise.
+    __version__ = "0.0.0.dev0"