feat(low-code): expose stream_slice to the paginator interpolation context

[Anatolii Yatsuk (tolik0)]

Closes #1166.

What

CursorPagination.stop_condition and cursor_value can now read the slice being paginated, as stream_slice, stream_interval or stream_partition, the same aliases the requester already offers.

pagination_strategy:
  type: CursorPagination
  cursor_value: "{{ response.next }}"
  stop_condition: >-
    {{ response.items and str_to_datetime(response.items[-1].created_at)
       < str_to_datetime(stream_interval.start_time) }}

Until now a stop condition that depends on the slice (stop once the page is older than the window start) needed a custom PaginationStrategy, and the slice had to reach it through a side channel. source-github did this by sending the window start in an X-Airbyte-Window-Start request header and reading it back off the prepared request (review thread).

How

• PaginationStrategy.next_page_token and Paginator.next_page_token take an optional stream_slice.
• SimpleRetriever / LazySimpleRetriever pass the slice each page was read for, including after a pagination reset, through DefaultPaginator, PaginatorTestReadDecorator and StopConditionPaginationStrategyDecorator down to the strategy.
• CursorPaginationStrategy adds it to the interpolation context of stop_condition and cursor_value. The built-in OffsetIncrement, PageIncrement and NoPagination accept and ignore it.

Backward compatibility

Custom paginators and strategies in connectors override next_page_token(self, response, last_page_size, last_record, last_page_token_value) without the new parameter. stream_slice_kwargs only passes stream_slice when the callee's signature declares stream_slice or **kwargs (cached per function), so those keep working unchanged. This follows the signature-gating used for page_size_override in #1149.

Tests

• CursorPaginationStrategy: a slice-dependent stop_condition over fresh, stale and empty pages, and a cursor_value read from stream_partition.
• DefaultPaginator, the test-read decorator and StopConditionPaginationStrategyDecorator: the slice is forwarded, and a strategy without the parameter is not handed it.
• SimpleRetriever: after a pagination reset, the paginator sees the slice each page was read for; a paginator without the parameter keeps working.
• unit_tests/sources/declarative: 2085 passed. ruff and mypy clean.

Adopter

airbytehq/airbyte source-github replaces WorkflowRunsPaginationStrategy and the X-Airbyte-Window-Start header with a stop_condition (PR to follow, pinned to a prerelease of this branch).

🤖 Generated with Claude Code

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

Testing This CDK Version

You can test this version of the CDK using the following:

# Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@tolik0/cdk/paginator-stream-slice#egg=airbyte-python-cdk[dev]' --help

# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch tolik0/cdk/paginator-stream-slice

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

• /autofix - Fixes most formatting and linting issues
• /poetry-lock - Updates poetry.lock file
• /test - Runs connector tests with the updated CDK
• /prerelease - Triggers a prerelease publish with default arguments
• /poe build - Regenerate git-committed build artifacts, such as the pydantic models which are generated from the manifest JSON schema in YAML.
• /poe <command> - Runs any poe command in the CDK environment

📚 Show Repo Guidance

Helpful Resources

• CDK API Reference

📝 Edit this welcome message.

[Anatolii Yatsuk (tolik0)]

/prerelease

Prerelease Job Info

This job triggers the publish workflow with default arguments to create a prerelease.

Prerelease job started... Check job output.

✅ Prerelease workflow triggered successfully.

View the publish workflow run: https://github.com/airbytehq/airbyte-python-cdk/actions/runs/35881424906

[github-actions]

PyTest Results (Fast)

4 685 tests  +11   4 673 ✅ +11   9m 48s ⏱️ -4s
    1 suites ± 0      12 💤 ± 0 
    1 files   ± 0       0 ❌ ± 0 

Results for commit a274d90. ± Comparison against base commit d8d8e6f.

[github-actions]

PyTest Results (Full)

4 688 tests  +11   4 676 ✅ +11   14m 28s ⏱️ +34s
    1 suites ± 0      12 💤 ± 0 
    1 files   ± 0       0 ❌ ± 0 

Results for commit a274d90. ± Comparison against base commit d8d8e6f.

[Copilot]

Copilot review overview

🟢 Approval recommended

No unresolved review issues were identified, and forwarding and compatibility are covered by tests.

Review effort: Lite
Findings: None

What changed in this PR

This PR exposes the active stream slice to cursor pagination expressions while preserving compatibility with existing custom implementations.

Changes:

• Propagates stream_slice through retrievers, paginators, decorators, and strategies.
• Adds slice aliases to cursor and stop-condition interpolation.
• Adds compatibility tests and schema documentation.

File	Summary
unit_tests/​sources/​declarative/​retrievers/​test_simple_retriever.py	Tests slice propagation across pagination resets and legacy paginators.
unit_tests/​sources/​declarative/​requesters/​paginators/​test_stop_condition.py	Tests decorator forwarding.
unit_tests/​sources/​declarative/​requesters/​paginators/​test_default_paginator.py	Tests strategy forwarding and compatibility.
unit_tests/​sources/​declarative/​requesters/​paginators/​test_cursor_pagination_strategy.py	Tests slice-dependent expressions.
airbyte_cdk/​sources/​declarative/​retrievers/​simple_retriever.py	Passes slices during page retrieval.
airbyte_cdk/​sources/​declarative/​requesters/​paginators/​strategies/​stop_condition.py	Forwards slices through the decorator.
airbyte_cdk/​sources/​declarative/​requesters/​paginators/​strategies/​pagination_strategy.py	Extends the strategy API.
airbyte_cdk/​sources/​declarative/​requesters/​paginators/​strategies/​page_increment.py	Accepts the optional slice.
airbyte_cdk/​sources/​declarative/​requesters/​paginators/​strategies/​offset_increment.py	Accepts the optional slice.
airbyte_cdk/​sources/​declarative/​requesters/​paginators/​strategies/​cursor_pagination_strategy.py	Exposes the slice to interpolation.
airbyte_cdk/​sources/​declarative/​requesters/​paginators/​paginator.py	Adds signature-aware slice forwarding.
airbyte_cdk/​sources/​declarative/​requesters/​paginators/​no_pagination.py	Accepts and ignores the optional slice.
airbyte_cdk/​sources/​declarative/​requesters/​paginators/​default_paginator.py	Propagates slices through paginator decorators.
airbyte_cdk/​sources/​declarative/​declarative_component_schema.yaml	Documents slice interpolation variables.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.