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.