[python] support continuation token for paging

[msyyc]

fix #5791
API design: https://gist.github.com/msyyc/02463a6dc5a150772bd8f0ae42d4cd37

Summary for this PR:

• Changes for continuation token in paging:

1. add new property isContinuationToken in parameter
2. add new property ContinuationTokenRequest/ContinuationTokenResponse for paging operation whose type is {wireName: string, position: "header" | "query" | "body"}
3. With new property isContinuationToken/ContinuationTokenRequest/ContinuationTokenResponse, it is much easier for pygen to generate related API
4. replace continuationTokenName which is actually used as with nextLinkName with nextLinkName

• replace some deprecated property of TCGC with recommended property
• optimize the logic to report diagnostics

[azure-sdk]

All changed packages have been documented.

• ✅ @typespec/http-client-python

Show changes

@typespec/http-client-python - feature ✏️

support continuation token for paging

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[Copilot]

PR Overview

This PR introduces support for continuation tokens in paging operations for the Python SDK. Key changes include:

• Adding the new property "isContinuationToken" to parameters.
• Introducing "ContinuationTokenRequest" and "ContinuationTokenResponse" properties to enhance paging operations.
• Replacing "continuationTokenName" with "nextLinkName" and updating associated logic across the generator and emitter modules.

Reviewed Changes

File	Description
packages/http-client-python/generator/test/generic_mock_api_tests/test_payload_pageable.py	Added test cases for various paging endpoints using continuation token design
packages/http-client-python/generator/test/generic_mock_api_tests/asynctests/test_payload_pageable_async.py	Added asynchronous test cases for new paging scenarios
packages/http-client-python/emitter/src/http.ts	Updated HTTP operation emission to support continuation tokens and next link handling
packages/http-client-python/emitter/src/utils.ts	Added and updated utility functions for handling continuation tokens
packages/http-client-python/generator/pygen/codegen/serializers/builder_serializer.py	Enhanced paging callback logic to incorporate continuation token extraction
packages/http-client-python/emitter/src/emitter.ts	Wrapped main emitter logic in error handling for improved diagnostics
packages/http-client-python/emitter/src/lib.ts	Added new diagnostic messages for missing continuation token wire names and positions
packages/http-client-python/generator/pygen/codegen/models/request_builder_parameter.py	Updated parameter naming logic to account for continuation tokens
packages/http-client-python/generator/pygen/codegen/models/paging_operation.py	Revised paging model to expose continuation token related properties and variable names
packages/http-client-python/generator/pygen/codegen/models/parameter.py	Added "isContinuationToken" property to parameter models

Copilot reviewed 13 out of 13 changed files in this pull request and generated no comments.

Comments suppressed due to low confidence (3)

packages/http-client-python/generator/pygen/codegen/models/request_builder_parameter.py:115

• [nitpick] The inline conditional expression for resolving the continuation token is somewhat ambiguous. Consider adding parentheses or restructuring the expression for improved clarity.

if self.is_continuation_token:
            return f"{self.client_name} if _continuation_token is None else _continuation_token"

packages/http-client-python/generator/pygen/codegen/models/response.py:66

• Chaining .get calls with a default of {} may unintentionally return an empty dictionary instead of a None value when fields are missing. Verify that this behavior aligns with the intended API expectations.

return "".join([f'.get("{field}", {{}})' for field in field.split(".")])

packages/http-client-python/generator/pygen/codegen/models/paging_operation.py:70

• [nitpick] Returning '_continuation_token' when a continuation token is present could be confusing given the overall naming conventions. Consider aligning this with the 'next_link' naming to maintain consistency.

return "_continuation_token" if self.has_continuation_token else "next_link"