airbytehq / airbytehq/airbyte-api-python-sdk

bug: airbyte-api 1.0.0 has forward-reference errors and breaking API changes vs 0.53.0

Open
#178 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.