From 1021326273a2c3ae054eeaf1d5b837fb5398d95c Mon Sep 17 00:00:00 2001 From: cloudant-sdks-automation <71659186+cloudant-sdks-automation@users.noreply.github.com> Date: Wed, 9 Jul 2025 16:18:44 +0000 Subject: [PATCH] docs(generated): remove beta from changes follower Generated SDK source code using: - Generator version 3.106.0 - Specification version 1.0.0-dev0.1.28 - Automation (cloudant-sdks) version eb3f950 --- README.md | 90 +++++++++++++++++++++++++++---------------------------- 1 file changed, 45 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 58a5c466..87167e09 100644 --- a/README.md +++ b/README.md @@ -45,13 +45,13 @@ to avoid surprises. * [Raw IO](#raw-io) * [Model classes vs dictionaries](#model-classes-vs-dictionaries) * [Further resources](#further-resources) - * [Changes feed follower (beta)](#changes-feed-follower-beta) + * [Changes feed follower](#changes-feed-follower) + [Introduction](#introduction) + [Modes of operation](#modes-of-operation) + [Configuring the changes follower](#configuring-the-changes-follower) + [Error suppression](#error-suppression) + [Follower operation](#follower-operation) - + [Checkpointing](#checkpointing) + + [Checkpoints](#checkpoints) + [Code examples](#code-examples-1) - [Initializing a changes follower](#initializing-a-changes-follower) - [Starting the changes follower](#starting-the-changes-follower) @@ -95,7 +95,7 @@ project: - Handles the authentication. - Familiar user experience with IBM Cloud SDKs. - Flexibility to use either built-in models or byte-based requests and responses for documents. -- Built-in [Changes feed follower](#changes-feed-follower-beta) (beta) +- Built-in [Changes feed follower](#changes-feed-follower) - Instances of the client are unconditionally thread-safe. ## Prerequisites @@ -725,13 +725,13 @@ print(response) - [Cloudant blog](https://blog.cloudant.com/): Many useful articles about how to optimize Cloudant for common problems. -### Changes feed follower (beta) +### Changes feed follower #### Introduction -The SDK provides a changes feed follower utility (currently beta). +The SDK provides a changes feed follower utility. This helper utility connects to the `_changes` endpoint and returns the individual change items. -It removes some of the complexity of using the `_changes` endpoint by setting some options automatically +It removes some complexity of using the `_changes` endpoint by setting some options automatically and providing error suppression and retries. *Tip: the changes feed often does not meet user expectations or assumptions.* @@ -743,18 +743,18 @@ to get a better understanding of the limitations and suitable use-cases before u There are two modes of operation: * Start mode - * Fetches the changes from the supplied `since` sequence (by default the feed will start from `now`). + * Fetches the changes from the supplied `since` sequence (in this mode follower defaults to reading the feed from `now`). * Fetches all available changes and then continues listening for new changes indefinitely unless encountering an end condition. * An example use case for this mode is event driven workloads. * Start one-off mode - * Fetches the changes from the supplied `since` sequence (by default the feed will start from the beginning). + * Fetches the changes from the supplied `since` sequence (in this mode follower defaults to reading the feed from the beginning). * Fetches all available changes and then stops when either there are no further changes pending or encountering an end condition. * An example use case for this mode is ETL style workloads. #### Configuring the changes follower The SDK's model of changes feed options is also used to configure the follower. -However, a subset of the options are invalid as they are configured internally by the implementation. +However, a subset of the options used internally by the follower implementation are invalid. Supplying these options when instantiating the follower causes an error. The invalid options are: * `descending` @@ -762,33 +762,33 @@ The invalid options are: * `heartbeat` * `lastEventId` - use `since` instead * `timeout` -* Only the value of `_selector` is permitted for the `filter` option. This restriction is because selector - based filters perform better than JavaScript backed filters. Configuring a non-selector based filter will - cause the follower to error. +* Follower permits only the value `_selector` for the `filter` option. This restriction is because selector + based filters perform better than JavaScript backed filters. Configuring a non-selector based filter + causes the follower to error. -Note that the `limit` parameter will terminate the follower at the given number of changes in either +Note that the `limit` parameter terminates the follower at the given number of changes in either operating mode. -The changes follower requires the client to have HTTP timeouts of at least 1 minute and will error during +The changes follower requires the client to have HTTP timeouts of at least 1 minute and errors during instantiation if it is insufficient. The default client configuration has sufficiently long timeouts. -For use-cases where these configuration limitations are deemed too restrictive then it is recommended to -write code to use the SDK's [POST `_changes` API](https://github.com/IBM/cloudant-python-sdk/tree/v0.10.4/examples#postchanges) instead of the follower. +For use-cases where these configuration limitations are too restrictive then write code to use the SDK's +[POST `_changes` API](https://github.com/IBM/cloudant-python-sdk/tree/v0.10.4/examples#postchanges) instead of the follower. #### Error suppression -By default, the changes follower will suppress transient errors indefinitely and attempt to run to completion or listen forever as +By default, the changes follower suppresses transient errors indefinitely and attempts to run to completion or listen forever as dictated by the operating mode. -For applications where that is not desirable an optional error tolerance duration may be specified to control the time since -the last successful response that transient errors will be suppressed. This can be used, for example, by applications as a grace period +For applications where that is not desirable configure the optional error tolerance duration. This controls the time since +the last successful response that the follower suppresses transient errors. An example usage is an application grace period before reporting an error and requiring intervention. There are some additional points to consider for error suppression: -* Errors considered terminal, for example, the database not existing or invalid credentials are never suppressed and will error immediately. -* The error suppression duration is not guaranteed to fire immediately after lapsing and should be considered a minimum suppression time. -* The changes follower will back-off between retries and as such may remain paused for a short while after the transient errors have resolved. -* If the underlying SDK client used to initialize the follower also has retries configured then errors could be suppressed for significantly - longer than the follower's configured error tolerance duration depending on the configuration options. +* Errors considered terminal, for example, the database not existing or invalid credentials are never suppressed and error immediately. +* The error suppression duration is not guaranteed to fire immediately after lapsing and is a minimum suppression time. +* The changes follower backs-off between retries and as such may remain paused for a short while after the transient errors have resolved. +* If the underlying SDK client used to initialize the follower also has retries configured then suppression of errors may last + significantly longer than the follower's configured error tolerance duration depending on the specific options. #### Follower operation @@ -797,41 +797,41 @@ For both modes: * A terminal error (HTTP codes `400`, `401`, `403` `404`). * Transient errors occur for longer than the error tolerance duration. Transient errors are all other HTTP status codes and connection errors. * The number of changes received reaches the configured `limit`. - * The feed is terminated early by calling stop. + * The application calls stop to terminate the feed early. -As is true for the `_changes` endpoint change items have *at least once* delivery and an individual item -may be received multiple times. When using the follower change items may be repeated even within a limited -number of changes (i.e. using the `limit` option) this is a minor difference from using `limit` on the HTTP native API. +As is true for the `_changes` endpoint change items have *at least once* delivery and callers may receive +an individual item multiple times. When using the follower change items may repeat even within a limited +number of changes (that is using the `limit` option) this is a minor difference from using `limit` on the HTTP native API. The follower is not optimized for some use cases and it is not recommended to use it in cases where: * Setting `include_docs` and larger document sizes (for example > 10 kiB). -* The volume of changes is very high (if the rate of changes in the database exceeds the follower's rate of pulling them it will never catch-up). +* The volume of changes is very high (if the rate of changes in the database exceeds the follower's rate of pulling them it can never catch-up). -In these cases use-case specific control over the number of change requests made and the content size of the responses -may be achieved by using the SDK's [POST `_changes` API](https://github.com/IBM/cloudant-python-sdk/tree/v0.10.4/examples#postchanges). +In these use-cases use the SDK's [POST `_changes` API](https://github.com/IBM/cloudant-python-sdk/tree/v0.10.4/examples#postchanges) +for specific control over the number of change requests made and the content size of the responses. -#### Checkpointing +#### Checkpoints -The changes follower does not checkpoint since it has no information about whether a change item has been -processed by the consuming application after being received. It is the application developer's responsibility +The changes follower does not checkpoint since it has no information about whether the consuming application +has processed a change item after delivery. It is the application developer's responsibility to store the sequence IDs to have appropriate checkpoints and to re-initialize the follower with the required `since` value after, for example, the application restarts. -The frequency and conditions for checkpointing are application specific and some applications may be tolerant -of dropped changes. This section is intended only to provide general guidance on how to avoid missing changes. +The frequency and conditions for checkpoints are application specific and some applications may be tolerant +of dropped changes. This section provides only general guidance on how to avoid missing changes. -To guarantee processing of all changes the sequence ID from a change item must not be persisted until *after* -the processing of the change item by the application has completed. As indicated previously change items are -delivered *at least once* so application code must be able to handle repeated changes already and it is +To guarantee processing of all changes do not persist the sequence ID from a change item until *after* +the processing of the change item by the application has completed. As indicated previously change item +delivery is *at least once* so application code must be able to handle repeated changes already. It is preferable to restart from an older `since` value and receive changes again than risk missing them. -The sequence IDs are available on each change item by default, but may be omitted from some change items when -using the `seq_interval` configuration option. Infrequent sequence IDs may improve performance by reducing -the amount of data that needs to be transferred, but the trade-off is that more changes will be repeated if -it is necessary to resume the changes follower. +The sequence IDs are available on each change item by default. However, the server omits sequence IDs from +some change items when using the `seq_interval` configuration option. +Infrequent sequence IDs may improve performance by reducing the amount of data transfer and server load, +but the tradeoff is repeating more changes if it is necessary to resume the changes follower. -Extreme care should be taken with persisting sequences if choosing to process change items in parallel as there -is a considerable risk of missing changes on a restart if the sequence is recorded out of order. +Take extreme care persisting sequences if choosing to process change items in parallel as there +is a considerable risk of missing changes on a restart if the recorded sequence is out of order. #### Code examples