Skip to content

Commit 1a2aff2

Browse files
stevapplestevapple
authored
Moves pagination helpers into Teco Core (#49)
* Moves pagination into `TecoCore` * Moves pagination documentation into `TecoCore` * Marks `TecoPaginationHelpers` as deprecated in documentation * Adds explicit topics arrangement for `TCClient` documentation * Improves documentation arrangement for error types * Corrects 'TecoCore' into 'Teco Core'
1 parent d476305 commit 1a2aff2

File tree

12 files changed

+93
-51
lines changed

12 files changed

+93
-51
lines changed

‎.spi.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,5 @@ builder:
44
- documentation_targets:
55
- TecoCore
66
- TecoDateHelpers
7-
- TecoPaginationHelpers
87
- TecoSigner
98
platform: linux

‎Sources/TecoCore/Common/TCClient.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ import TecoSigner
3636

3737
/// Client managing communication with Tencent Cloud services.
3838
///
39-
/// This is the workhorse of TecoCore. You provide it with a ``TCRequest``, it converts it to `TCHTTPRequest` which is then converted to a raw `HTTPClient` request. This is then sent to Tencent Cloud.
39+
/// This is the workhorse of Teco Core. You provide it with a ``TCRequest``, it converts it to `TCHTTPRequest` which is then converted to a raw `HTTPClient` request. This is then sent to Tencent Cloud.
4040
///
4141
/// When the response from Tencent Cloud is received, it will be converted to a `TCHTTPResponse`, which is then decoded to generate a ``TCResponse`` or to create and throw a ``TCErrorType``.
4242
public final class TCClient: _TecoSendable {

‎Sources/TecoCore/Documentation.docc/TCClient.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# ``TCClient``
2+
3+
## Discussions
4+
5+
Some Tencent Cloud APIs provide query functionality and may return a list of objects with arbitrary length. Most of them come with support for paginating the list, i.e., they will return the list in fixed-size chunks, sometimes also with a token to be used in the next request.
6+
7+
``TCClient`` has integrated support for accessing the full paginated results either synchronously and asynchrously, through pagination and paginator APIs.
8+
9+
## Topics
10+
11+
### Configurating the Client
12+
13+
- ``init(credentialProvider:retryPolicy:options:httpClientProvider:logger:)``
14+
15+
- ``HTTPClientProvider``
16+
- ``Options``
17+
18+
- ``credentialProvider``
19+
- ``retryPolicy``
20+
- ``eventLoopGroup``
21+
- ``httpClient``
22+
23+
### Executing an API Request
24+
25+
- ``execute(action:path:region:httpMethod:serviceConfig:skipAuthorization:outputs:logger:on:)``
26+
- ``execute(action:path:region:httpMethod:serviceConfig:skipAuthorization:input:outputs:logger:on:)-1aise``
27+
- ``execute(action:path:region:httpMethod:serviceConfig:skipAuthorization:input:outputs:logger:on:)-63804``
28+
29+
### Executing a Paginated Request
30+
31+
- ``paginate(input:region:command:initialValue:reducer:logger:on:)``
32+
- ``paginate(input:region:command:logger:on:)``
33+
- ``paginate(input:region:command:callback:logger:on:)``
34+
35+
### Retrieving Paginated Results
36+
37+
- ``Paginator``
38+
- ``PaginatorSequences``
39+
- ``Paginator/makeAsyncSequences(input:region:command:logger:on:)``
40+
41+
### Shutting Down the Client
42+
43+
- ``shutdown(queue:_:)``
44+
- ``syncShutdown()``
45+
46+
### Utilities
47+
48+
- ``loggingDisabled``
49+
- ``getCredential(on:logger:)``
50+
- ``signHeaders(url:method:headers:body:serviceConfig:skipAuthorization:logger:)``
51+
- ``signHeaders(url:httpMethod:headers:body:serviceConfig:skipAuthorization:logger:)``

Sources/TecoPaginationHelpers/Documentation.docc/TCPaginatedResponse.md renamed to Sources/TecoCore/Documentation.docc/TCPaginatedResponse.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# ``TecoPaginationHelpers/TCPaginatedResponse``
1+
# ``TCPaginatedResponse``
22

33
## Discussion
44

Sources/TecoPaginationHelpers/Documentation.docc/TCPaginatedResponse/Count.md renamed to Sources/TecoCore/Documentation.docc/TCPaginatedResponse/Count.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
# ``TecoPaginationHelpers/TCPaginatedResponse/Count``
1+
# ``TCPaginatedResponse/Count``
22

33
## Discussion
44

5-
Most paginated Tencent Cloud APIs return the total element count for the queried items in a `BinaryInteger`, eg. `UInt64`. We use this value to ensure the queried result didn't change during pagination, and will throw a ``TecoPaginationHelpers/TecoCore/TCClient/PaginationError/totalCountChanged`` error if it changed unexpectedly.
5+
Most paginated Tencent Cloud APIs return the total element count for the queried items in a `BinaryInteger`, eg. `UInt64`. We use this value to ensure the queried result didn't change during pagination, and will throw a ``TCClient/PaginationError/totalCountChanged`` error if it changed unexpectedly.
66

7-
Some paginated API responses, however, doesn't have a total count field. For these response models, ``Count`` should be `Never` and ``getTotalCount()-9zl99`` will always return `nil`.
7+
Some paginated API responses, however, doesn't have a total count field. For these response models, ``Count`` should be `Never` and ``getTotalCount()-6kxsn`` will always return `nil`.

‎Sources/TecoCore/Documentation.docc/index.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,13 @@ This library provides most common functionalities around calling Tencent Cloud A
3434
- ``TCOutputModel``
3535

3636
- ``TCRequest``
37-
- ``TCRequestModel``
37+
- ``TCMultipartRequest``
38+
- ``TCPaginatedRequest``
3839

3940
- ``TCResponse``
41+
- ``TCPaginatedResponse``
42+
43+
- ``TCRequestModel``
4044
- ``TCResponseModel``
4145

4246
### Credentials
@@ -66,7 +70,10 @@ This library provides most common functionalities around calling Tencent Cloud A
6670
- ``EndpointProvider``
6771
- ``EndpointProviderFactory``
6872

69-
### Error handling
73+
### Error Handling
74+
75+
- ``TCClient/ClientError``
76+
- ``TCClient/PaginationError``
7077

7178
- ``TCErrorContext``
7279

Sources/TecoPaginationHelpers/TCClient+Pagination.swift renamed to Sources/TecoCore/Pagination/TCClient+Pagination.swift

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@
1313

1414
import NIOCore
1515
import Logging
16-
import TecoCore
1716

1817
extension TCClient {
1918
/// Execute a series of paginated requests and return a future with the combined result generated from the responses.

Sources/TecoPaginationHelpers/TCClient+PaginationError.swift renamed to Sources/TecoCore/Pagination/TCClient+PaginationError.swift

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,8 @@
1111
//
1212
//===----------------------------------------------------------------------===//
1313

14-
import TecoCore
15-
1614
extension TCClient {
17-
/// Errors returned by `TCClient` pagination helpers.
15+
/// Errors returned by ``TCClient`` pagination helpers.
1816
public enum PaginationError: Error, Equatable {
1917
/// Total item count changed during pagination.
2018
case totalCountChanged

Sources/TecoPaginationHelpers/TCClient+Paginator.swift renamed to Sources/TecoCore/Pagination/TCClient+Paginator.swift

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@
1313

1414
import Logging
1515
import NIOCore
16-
import TecoCore
1716

1817
extension TCClient {
1918
/// Tuple consisting of async sequences returned by the paginator.

Sources/TecoPaginationHelpers/TCPaginatedModel.swift renamed to Sources/TecoCore/Pagination/TCPaginatedModel.swift

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,7 @@
1111
//
1212
//===----------------------------------------------------------------------===//
1313

14-
import TecoCore
15-
16-
#if swift(>=5.6)
17-
public typealias _PaginationSendable = Sendable
18-
#else
19-
public typealias _PaginationSendable = Any
20-
#endif
21-
22-
/// Tencent Cloud API request model that represents a paginated query.
14+
/// ``TCRequest`` that represents a paginated query.
2315
public protocol TCPaginatedRequest: TCRequest {
2416
/// Paginated response type associated with the request.
2517
associatedtype Response: TCPaginatedResponse
@@ -28,12 +20,12 @@ public protocol TCPaginatedRequest: TCRequest {
2820
func makeNextRequest(with response: Response) -> Self?
2921
}
3022

31-
/// Tencent Cloud API response model that contains a list of paginated result and a total count.
23+
/// ``TCResponse`` that contains a list of paginated result and a total count.
3224
public protocol TCPaginatedResponse: TCResponse {
3325
/// The total count type to be extracted from the response.
34-
associatedtype Count: _PaginationSendable, Equatable
26+
associatedtype Count: _TecoSendable, Equatable
3527
/// The queried item type.
36-
associatedtype Item: _PaginationSendable
28+
associatedtype Item: _TecoSendable
3729

3830
/// Extract the total count from the paginated response.
3931
func getTotalCount() -> Count?

0 commit comments

Comments
 (0)