Repository navigation
chore(none): decommission dead Speakeasy generator scaffolding - #349
Merged
Merged
Conversation
CyMule
force-pushed
the
chore/decommission-speakeasy-scaffolding
branch
from
August 5, 2026 02:41
6ce2013 to
e4b12e8
Compare
…caffolding and fix the docs describing it
CyMule
force-pushed
the
chore/decommission-speakeasy-scaffolding
branch
from
August 5, 2026 02:56
e4b12e8 to
4fbfbd3
Compare
Collaborator
|
Thank you thank you! Ping me when it's out of draft and I can approve |
awalker4
marked this pull request as ready for review
September 25, 2026 00:55
Resolve RELEASES.md modify/delete conflict by keeping the deletion; main's new entries (0.46.1, 0.46.2) are Speakeasy ledger boilerplate and the human-facing notes already live in CHANGELOG.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
awalker4
changed the title
awalker4
approved these changes
Sep 25, 2026
CyMule
added a commit
that referenced
this pull request
Oct 21, 2026
) ## What Jobs the new preflight check rejects no longer break the SDK. Workflows can also opt out of preflight from the SDK. **Before**, after a job is rejected: ``` client.jobs.list_jobs(...) → ValidationError: 'REJECTED' is not a valid JobStatus (whole page lost) client.jobs.get_job(...) → ValidationError ``` **After:** ``` job.status → JobStatus.REJECTED job.status → "SOME_FUTURE_STATUS" # a status this SDK version doesn't know comes back as a plain str instead of raising details.node_stats[0].failure_category → PreflightFailureCategory.AUTH_INVALID_CREDENTIAL details.node_stats[0].failure_reason → "The AWS Access Key Id you provided does not exist." ``` - `JobStatus` and `JobProcessingStatus` gain `REJECTED`. `JobInformation.status` and `JobDetails.processing_status` also accept unknown values. Known values are still enum members, so `job.status == JobStatus.COMPLETED` and `.value` behave as before. - `JobNodeDetails` gains `failure_category` (`Union[PreflightFailureCategory, str]`) and `failure_reason`, so a caller can see why a job was rejected. The server sets them only on the node that failed preflight; before this, pydantic dropped them. - `skip_preflight` is now on `CreateWorkflow`, `UpdateWorkflow` (unset = unchanged) and `WorkflowInformation`. For a one-off `create_job`, the API defines the flag inside the `request_data` JSON. The docs now say to set it there; the SDK does not rewrite that string. - Releases as **0.47.0**. ## Why The SDK models used to be regenerated from the API spec every night. That generator has been dead since January (removed in #349). Since then, new server values reach the SDK only when someone adds them by hand. `REJECTED` didn't get added, and a closed enum turns a new value into a hard failure. This PR also adds a way to catch that kind of drift before a customer does (DTPL-696 acceptance criterion 4): ``` weekly CI → fetch live OpenAPI specs → compare with SDK models → new missing field/enum value → open/update a GitHub issue (a failed download fails the run but opens no issue) ``` - `make check-spec-drift` runs the check locally. Gaps we already know about are recorded in `scripts/spec_drift_baseline.json` (20 schemas today, e.g. `JobInformation.processing_status`, the `teradata` connector type). The check fails only on new drift, or on a baseline entry that has since been covered. - `CONTRIBUTING.md` documents how to resolve a drift issue. Replaces #353, which got here through a custom `_missing_` enum hook and code that spliced bytes into `request_data`. This version uses a plain pydantic union and leaves `request_data` alone. ## Notes for consumers - Type checkers now see these two status fields as `Union[JobStatus, str]` / `Union[JobProcessingStatus, str]`. Code that reads `.value` or `.name` on them needs to handle the `str` case. Runtime behavior for known statuses is unchanged. - Follow-up, not in this PR: the SDK's other "open" enums (connector types, partition `Strategy`, etc.) use `OpenEnumMeta` / `validate_open_enum`. On Python 3.12+ those return a raw `str` even for known values, and they emit pydantic serializer warnings. The long-term fix is to move them to the same union pattern used here. That changes their runtime types, so it belongs in its own PR. ## Validation - `make test-unit`: 419 passed. `make test-contract`: 72 passed. The new job/workflow contract tests pass on Python 3.11, 3.12 and 3.13, and they fail without the model changes. - `make lint` is clean. `make check-spec-drift` passes against the live specs. - Two rounds of Codex review. Round 1 found that enums declared inline on a property escaped the drift check; that is fixed and has a test. Round 2 was clean. - cubic: three findings fixed (no drift issue on a fetch failure, no duplicate issues from overlapping runs, changelog wording). Re-review clean, and full CI is green, including integration on 3.11–3.13. ## Maintenance validation (2026-10-19, keepalive base refresh) - Synchronized main through its 0.46.5 keepalive release while retaining the authored 0.47.0 version and user-agent. Manual conflict resolution touched only the changelog and version file; main runtime and test changes merged automatically. - Local validation: 419 unit tests and 71 contract tests passed (one existing expected unit failure). Four localhost socket tests needed bind permission and passed without source changes. - Exact maintenance-head CI: https://github.com/Unstructured-IO/unstructured-python-client/actions/runs/39329146842. ## Review follow-up (2026-10-20) - Added `failure_category` / `failure_reason` to `JobNodeDetails` with a new `PreflightFailureCategory` enum, and dropped both from the drift baseline. A new contract test covers a known category, an unknown category (plain `str`) and a passing node (both null); it passes on 3.11, 3.12 and 3.13. - Removed the `JobStatus` / `JobProcessingStatus` entries from `overlay_client.yaml`. Nothing reads the overlay since the generator was removed, and `x-speakeasy-unknown-values` would describe the `OpenEnumMeta` style, not the union shipped here. - `make test-unit` 419 passed, `make test-contract` 72 passed, `make lint` clean, `make check-spec-drift` clean against the live specs. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
SDK generation has been blocked at the Speakeasy account level for months —
.speakeasy/gen.lockhasn't moved since #324 (2026-01-18). Removes the generator input, output, and tooling that can no longer run.No changes under
src/— the shipped SDK is byte-identical.What's deleted
.speakeasy/gen.lock(1,581)RELEASES.md(1,253)CHANGELOG.mdis the human changelog, untouchedcodeSamples.yaml(185)_jupyter/README_example.ipynb(112)tests/helpers.py(61)_test_unstructured_client/and_test_contract/USAGE.md(42)## SDK Example Usagesection inREADME.mdfiles.gen(29).github/workflows/speakeasy_sdk_generation.yml(25)speakeasy-api/sdk-generation-actionPlus the 7 speakeasy/jupyter Makefile targets and the 28 generator marker comments in
README.md.Docs
CONTRIBUTING.mdand the README Contributions section tell contributors to install the Speakeasy CLI and runmake client-generate, a target that no longer exists. Reworded to drop the generator mechanics.Regeneration
overlay_client.yamlis left in place — it's hand-written input, not generator output, and the sole source of thesplit_pdf_*parameter descriptions..genignore,gen.yamland.speakeasy/workflow.yamlalso stay.If access is restored, regeneration is messier but not blocked:
gen.lockcarries the target UUID, and without the README markers a regen appends sections rather than replacing them in place.Test plan
make test-unit— 249 passed, 1 xfailed (baseline)make test-contract— 64 passedmake lint— mypy clean, pylint 10.00/10