diff --git a/src/data/languages/languageData.ts b/src/data/languages/languageData.ts index f413676543..0b08361592 100644 --- a/src/data/languages/languageData.ts +++ b/src/data/languages/languageData.ts @@ -13,7 +13,7 @@ export default { kotlin: '1.6', objc: '1.2', php: '1.1', - python: '2.1', + python: '3.0', ruby: '1.2', swift: '1.2', go: '1.3', @@ -29,7 +29,7 @@ export default { kotlin: '1.6', objc: '1.2', php: '1.1', - python: '2.1', + python: '3.0', ruby: '1.2', swift: '1.2', go: '1.3', diff --git a/src/pages/docs/api/realtime-sdk/channels.mdx b/src/pages/docs/api/realtime-sdk/channels.mdx index 826a4d7fe2..72bff23da3 100644 --- a/src/pages/docs/api/realtime-sdk/channels.mdx +++ b/src/pages/docs/api/realtime-sdk/channels.mdx @@ -824,7 +824,7 @@ Failure to retrieve the message history will trigger the `errback` callbacks of - + #### getMessage @@ -836,6 +836,10 @@ Failure to retrieve the message history will trigger the `errback` callbacks of `Message getMessage(String serial)` + +`Message get_message(serial_or_message)` + + Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities). See [updating and deleting messages: retrieving the latest version](/docs/messages/updates-deletes#get) for more information. @@ -862,6 +866,18 @@ Returns a promise which, upon success, will be fulfilled with a [`Message`](/doc Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. + +| Parameter | Description | Type | +|-----------|-------------|------| +| serial_or_message | Either the serial identifier string of the message to retrieve, or a `Message` object containing a populated `serial` field | `str` or `Message` | + +##### Returns + +Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. + +On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + + #### updateMessage @@ -872,6 +888,10 @@ Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the l `void updateMessage(Message message, MessageOperation operation, Callback callback)` + +`UpdateDeleteResult update_message(message, operation=None, params=dict())` + + Publishes an update to an existing message with shallow mixin semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities). See [updating and deleting messages: updates](/docs/messages/updates-deletes#update) for more information. @@ -895,6 +915,14 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR Invokes the provided `Callback` with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message on success, or with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object describing the error on failure. + +##### Returns + +Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + + #### deleteMessage @@ -905,6 +933,10 @@ Invokes the provided `Callback` with an [`UpdateDeleteResult `void deleteMessage(Message message, MessageOperation operation, Callback callback)` + +`UpdateDeleteResult delete_message(message, operation=None, params=dict())` + + Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses shallow mixin semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-delete-own** or **message-delete-any** [capability](/docs/auth/capabilities). See [updating and deleting messages: deletes](/docs/messages/updates-deletes#delete) for more information. @@ -928,6 +960,14 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR Invokes the provided `Callback` with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message on success, or with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object describing the error on failure. + +##### Returns + +Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + + #### appendMessage @@ -938,6 +978,10 @@ Invokes the provided `Callback` with an [`UpdateDeleteResult `void appendMessage(Message message, MessageOperation operation, Callback callback)` + +`UpdateDeleteResult append_message(message, operation=None, params=dict())` + + Appends data to an existing message. The supplied `data` field is appended to the previous message's data, while all other fields (`name`, `extras`) replace the previous values if provided. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities). See [updating and deleting messages: appends](/docs/messages/updates-deletes#append) for more information. @@ -961,6 +1005,14 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR Invokes the provided `Callback` with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message on success, or with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object describing the error on failure. + +##### Returns + +Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + + #### getMessageVersions @@ -971,6 +1023,10 @@ Invokes the provided `Callback` with an [`UpdateDeleteResult `PaginatedResult getMessageVersions(String serial, Param[] params)` + +`PaginatedResult get_message_versions(serial_or_message, params = dict())` + + Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/auth/capabilities). See [updating and deleting messages: message versions](/docs/messages/updates-deletes#versions) for more information. @@ -988,7 +1044,7 @@ See [updating and deleting messages: message versions](/docs/messages/updates-de Returns a promise which, upon success, will be fulfilled with a [`PaginatedResult`](#paginated-result) object containing an array of [`Message`](/docs/api/realtime-sdk/messages) objects representing all versions of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. - + ##### Returns On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods. diff --git a/src/pages/docs/api/rest-sdk/channels.mdx b/src/pages/docs/api/rest-sdk/channels.mdx index 979af1114d..98709998bb 100644 --- a/src/pages/docs/api/rest-sdk/channels.mdx +++ b/src/pages/docs/api/rest-sdk/channels.mdx @@ -465,7 +465,7 @@ On failure to retrieve message history, the `error` contains an [`ErrorInfo`](#e - + #### getMessage @@ -477,6 +477,10 @@ On failure to retrieve message history, the `error` contains an [`ErrorInfo`](#e `Message getMessage(String serial)` + +`Message get_message(serial_or_message)` + + Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities). See [updating and deleting messages: retrieving the latest version](/docs/messages/updates-deletes#get) for more information. @@ -503,6 +507,18 @@ Returns a promise which, upon success, will be fulfilled with a [`Message`](/doc Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. + +| Parameter | Description | Type | +|-----------|-------------|------| +| serial_or_message | Either the serial identifier string of the message to retrieve, or a `Message` object containing a populated `serial` field | `str` or `Message` | + +##### Returns + +Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. + +On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + + #### updateMessage @@ -513,6 +529,10 @@ Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the l `UpdateDeleteResult updateMessage(Message message, MessageOperation operation)` + +`UpdateDeleteResult update_message(message, operation=None, params=dict())` + + Publishes an update to an existing message with shallow mixin semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities). See [updating and deleting messages: updates](/docs/messages/updates-deletes#update) for more information. @@ -531,7 +551,7 @@ See [updating and deleting messages: updates](/docs/messages/updates-deletes#upd Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. - + ##### Returns Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. @@ -547,6 +567,10 @@ Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-res `UpdateDeleteResult deleteMessage(Message message, MessageOperation operation)` + +`UpdateDeleteResult delete_message(message, operation=None, params=dict())` + + Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses shallow mixin semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-delete-own** or **message-delete-any** [capability](/docs/auth/capabilities). See [updating and deleting messages: deletes](/docs/messages/updates-deletes#delete) for more information. @@ -565,7 +589,7 @@ See [updating and deleting messages: deletes](/docs/messages/updates-deletes#del Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. - + ##### Returns Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. @@ -581,6 +605,10 @@ Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-res `UpdateDeleteResult appendMessage(Message message, MessageOperation operation)` + +`UpdateDeleteResult append_message(message, operation=None, params=dict())` + + Appends data to an existing message. The supplied `data` field is appended to the previous message's data, while all other fields (`name`, `extras`) replace the previous values if provided. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities). For publishing a high rate of appends, you typically want to use a realtime client, not a REST client, in order to have message order preservation. See [append ordering](/docs/messages/updates-deletes#append-ordering). @@ -601,7 +629,7 @@ See [updating and deleting messages: appends](/docs/messages/updates-deletes#app Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. - + ##### Returns Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. @@ -617,6 +645,10 @@ Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-res `PaginatedResult getMessageVersions(String serial, Param[] params)` + +`PaginatedResult get_message_versions(serial_or_message, **params)` + + Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/auth/capabilities). See [updating and deleting messages: versions](/docs/messages/updates-deletes#versions) for more information. @@ -634,7 +666,7 @@ See [updating and deleting messages: versions](/docs/messages/updates-deletes#ve Returns a promise which, upon success, will be fulfilled with a [`PaginatedResult`](#paginated-result) object containing an array of [`Message`](/docs/api/realtime-sdk/messages) objects representing all versions of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. - + ##### Returns On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods. diff --git a/src/pages/docs/messages/updates-deletes.mdx b/src/pages/docs/messages/updates-deletes.mdx index afd8cc00e3..1da0630dce 100644 --- a/src/pages/docs/messages/updates-deletes.mdx +++ b/src/pages/docs/messages/updates-deletes.mdx @@ -163,6 +163,21 @@ channel.updateMessage(message, operation, new Callback() { }); updateFuture.get(); ``` + +```python +realtime = AblyRealtime("{{API_KEY}}") +# This assumes there is an 'updates' namespace with a channel rule enabling updates and deletes +channel = realtime.channels.get("updates:example") + +# Publish the original message and get its serial from the result +publish_result = await channel.publish("message-name", "original-data") +serial = publish_result.serials[0] + +message = Message(data="updated-data", serial=serial) +operation = MessageOperation(description="reason for update") +result = await channel.update_message(message, operation) +print("Message updated") +``` #### Returns @@ -332,6 +347,21 @@ channel.deleteMessage(message, operation, new Callback() { }); deleteFuture.get(); ``` + +```python +realtime = AblyRealtime("{{API_KEY}}") +# This assumes there is an 'updates' namespace with a channel rule enabling updates and deletes +channel = realtime.channels.get("updates:example") + +# Publish the original message and get its serial from the result +publish_result = await channel.publish("message-name", "original-data") +serial = publish_result.serials[0] + +message = Message(data="", serial=serial) # clear the previous data +operation = MessageOperation(description="reason for delete") +result = await channel.delete_message(message, operation) +print("Message deleted") +``` #### Returns @@ -480,6 +510,25 @@ appendFuture.get(); // the message in history now has data: "Hello, World!" ``` +```python +realtime = AblyRealtime("{{API_KEY}}") +# This assumes there is an 'updates' namespace with a channel rule enabling updates and deletes +channel = realtime.channels.get("updates:example") + +# Publish the original message and get its serial from the result +publish_result = await channel.publish("message-name", "Hello") +serial = publish_result.serials[0] + +message1 = Message(data=" , ", serial=serial) +channel.append_message(message1) +message2 = Message(data="World", serial=serial) +channel.append_message(message2) +message3 = Message(data="!", serial=serial) +result = await channel.append_message(message3) + +# the message in history now has data: "Hello, World!" +``` + ```swift import Ably @@ -609,6 +658,16 @@ String serial = "0123456789-001@abcdefghij:001"; Message message = channel.getMessage(serial); ``` + +```python +rest = AblyRest("{{API_KEY}}") +channel = rest.channels.get("updates:example") + +# Example serial; for example from the `serial` property of a `Message` you previously received +serial = "0123456789-001@abcdefghij:001" + +message = await channel.get_message(serial) +``` ## Get message versions @@ -664,6 +723,17 @@ String serial = "0123456789-001@abcdefghij:001"; PaginatedResult page = channel.getMessageVersions(serial); System.out.println("Found " + page.items().length + " versions"); ``` + +```python +rest = AblyRest("{{API_KEY}}") +channel = rest.channels.get("updates:example") + +# Example serial; for example from the `serial` property of a `Message` you previously received +serial = "0123456789-001@abcdefghij:001" + +page = await channel.getMessageVersions(serial) +print("Found " + len(page.items) + " versions"); +``` ## Message version structure