airbytehq / airbytehq/airbyte-api-python-sdk
bug: airbyte-api 1.0.0 has forward-reference errors and breaking API changes vs 0.53.0
- 主要语言
- Python
- 星标
- 61
- 派生
- 27
- 平均合并
- 4 分钟
- 30 天内合并 PR
- 2
描述
## 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)
贡献指南
调研方向
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.
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- python
- 领域
- api
- Issue 类型
- 缺陷
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 活跃度
- 冷清
- 描述清晰度
- 基本清楚
- 新手友好度
- 42/100