airbytehq / airbytehq/airbyte-api-python-sdk
bug: airbyte-api 1.0.0 has forward-reference errors and breaking API changes vs 0.53.0
- Dominant language
- Python
- Stars
- 61
- Forks
- 27
- Avg merge
- 4m
- Merged PRs (30d)
- 2
Description
## Summary
`airbyte-api==1.0.0` introduces three categories of breaking changes that prevent [PyAirbyte](https://github.com/airbytehq/PyAirbyte) from upgrading. Full regression test results are in [airbytehq/PyAirbyte#1048](https://github.com/airbytehq/PyAirbyte/pull/1048).
## 1. Forward-reference errors in generated models (code generation bug)
Two models have forward-reference issues where classes/enums are used before they are defined:
### `SourceResponse` — `NameError` on import
```python
from airbyte_api.models import SourceResponse
# NameError: name "SourceGoogleAnalyticsDataAPISchemasCustomReportsArrayDimensionFilter
# DimensionsFilter2ExpressionsFilterFilter4ToValueValueType" is not defined
```
**Root cause:** In `source_google_analytics_data_api_schemas_custom_reports_array_int64value.py`, the enum `...Filter4ToValueValueType` is referenced at line 1422 (inside a class body) but defined at line 1457. Python evaluates class bodies eagerly, so the name is not yet available.
### `ConnectionResponse` — `PydanticUserError` on construction
```python
models.ConnectionResponse(connection_id="x", ...)
# pydantic.errors.PydanticUserError: `ConnectionResponse` is not fully defined;
# you should define `RowFilteringOperationNot`, then call `ConnectionResponse.model_rebuild()`.
```
**Root cause:** Same class of issue — a Pydantic model references `RowFilteringOperationNot` as a forward reference, but it has not been resolved when the model is first used.
Both are code-generation ordering bugs — the Speakeasy generator is emitting class definitions in the wrong order.
## 2. API method signatures changed to keyword-only arguments
All SDK resource methods (e.g., `Workspaces.get_workspace`, `Sources.create_source`, `Jobs.list_jobs`, etc.) now require `request=` to be passed as a **keyword argument**. In 0.53.0, positional passing was allowed. This is a breaking change for all existing callers.
Example — this worked in 0.53.0 but fails in 1.0.0:
```python
# 0.53.0 (works)
api_instance.workspaces.get_workspace(api.GetWorkspaceRequest(workspace_id="..."))
# 1.0.0 (requires keyword)
api_instance.workspaces.get_workspace(request=api.GetWorkspaceRequest(workspace_id="..."))
```
Pyrefly reports **39 type errors** across `airbyte/_util/api_util.py`: `[unexpected-positional-argument]`, `[bad-argument-count]`, and `[bad-argument-type]`.
## 3. Response type changes break duck-typing protocols
Response objects (e.g., `CreateWorkspaceResponse`, `ListJobsResponse`, `PatchSourceResponse`) have a changed `.raw_response` type that is no longer structurally compatible with PyAirbyte's `AirbyteApiResponseDuckType` protocol. Pyrefly reports these as `[bad-argument-type]` errors.
## Impact
- **474 of 484 tests pass** when the 2 broken test modules are excluded
- **All 7 required CI checks fail** on the full suite
- Core imports (`ConnectionResponse`, `DestinationResponse`, `JobResponse`, `WorkspaceResponse`, `JobStatusEnum`) work fine
- The forward-reference issues (#1) are bugs in the SDK itself; the signature changes (#2, #3) require PyAirbyte code updates
## Reproduction
```bash
pip install airbyte-api==1.0.0
python -c "from airbyte_api.models import SourceResponse" # NameError
```
## Environment
- Python 3.10, 3.11, 3.12 (all affected)
- Ubuntu and Windows (all affected)
- airbyte-api 0.53.0 → 1.0.0
---
[Devin session](https://app.devin.ai/sessions/84168ffdefe74522bb6d0cad34fcbb0b)
Contributor guide
Research direction
Start by running the documented airbyte-api==1.0.0 reproduction for SourceResponse, then inspect source_google_analytics_data_api_schemas_custom_reports_array_int64value.py around lines 1422 and 1457. Check ConnectionResponse construction and compare the SDK resource method signatures and response types with PyAirbyte#1048, especially airbyte/_util/api_util.py. Done should be defined for the SDK bugs separately from any required PyAirbyte compatibility updates.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100