Merge pull request #3148 from ably/AIT-289/python-mutable-messages-docs

[AIT-289] feat: ably-python mutable messages docs

Author: ttypic

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',

src/pages/docs/api/realtime-sdk/channels.mdx

@@ -824,7 +824,7 @@ Failure to retrieve the message history will trigger the `errback` callbacks of
 
 </If>
 
-<If lang="javascript,nodejs,java">
+<If lang="javascript,nodejs,java,python">
 
 #### getMessage
 
@@ -836,6 +836,10 @@ Failure to retrieve the message history will trigger the `errback` callbacks of
 `Message getMessage(String serial)`
 </If>
 
+<If lang="python">
+`Message get_message(serial_or_message)`
+</If>
+
 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.
 </If>
 
+<If lang="python">
+| 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).
+</If>
+
 #### updateMessage
 
 <If lang="javascript,nodejs">
@@ -872,6 +888,10 @@ Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the l
 `void updateMessage(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
 </If>
 
+<If lang="python">
+`UpdateDeleteResult update_message(message, operation=None, params=dict())`
+</If>
+
 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<UpdateDeleteResult>` 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.
 </If>
 
+<If lang="python">
+##### 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).
+</If>
+
 #### deleteMessage
 
 <If lang="javascript,nodejs">
@@ -905,6 +933,10 @@ Invokes the provided `Callback<UpdateDeleteResult>` with an [`UpdateDeleteResult
 `void deleteMessage(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
 </If>
 
+<If lang="python">
+`UpdateDeleteResult delete_message(message, operation=None, params=dict())`
+</If>
+
 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<UpdateDeleteResult>` 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.
 </If>
 
+<If lang="python">
+##### 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).
+</If>
+
 #### appendMessage
 
 <If lang="javascript,nodejs">
@@ -938,6 +978,10 @@ Invokes the provided `Callback<UpdateDeleteResult>` with an [`UpdateDeleteResult
 `void appendMessage(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
 </If>
 
+<If lang="python">
+`UpdateDeleteResult append_message(message, operation=None, params=dict())`
+</If>
+
 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<UpdateDeleteResult>` 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.
 </If>
 
+<If lang="python">
+##### 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).
+</If>
+
 #### getMessageVersions
 
 <If lang="javascript,nodejs">
@@ -971,6 +1023,10 @@ Invokes the provided `Callback<UpdateDeleteResult>` with an [`UpdateDeleteResult
 `PaginatedResult<Message> getMessageVersions(String serial, Param[] params)`
 </If>
 
+<If lang="python">
+`PaginatedResult get_message_versions(serial_or_message, params = dict())`
+</If>
+
 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.
 </If>
 
-<If lang="java">
+<If lang="java,python">
 ##### 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.

src/pages/docs/api/rest-sdk/channels.mdx

@@ -465,7 +465,7 @@ On failure to retrieve message history, the `error` contains an [`ErrorInfo`](#e
 
 </If>
 
-<If lang="javascript,nodejs">
+<If lang="javascript,nodejs,java,python">
 
 #### getMessage <a id="get-message" />
 
@@ -477,6 +477,10 @@ On failure to retrieve message history, the `error` contains an [`ErrorInfo`](#e
 `Message getMessage(String serial)`
 </If>
 
+<If lang="python">
+`Message get_message(serial_or_message)`
+</If>
+
 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.
 </If>
 
+<If lang="python">
+| 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).
+</If>
+
 #### updateMessage <a id="update-message" />
 
 <If lang="javascript,nodejs">
@@ -513,6 +529,10 @@ Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the l
 `UpdateDeleteResult updateMessage(Message message, MessageOperation operation)`
 </If>
 
+<If lang="python">
+`UpdateDeleteResult update_message(message, operation=None, params=dict())`
+</If>
+
 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.
 </If>
 
-<If lang="java">
+<If lang="java, python">
 ##### 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)`
 </If>
 
+<If lang="python">
+`UpdateDeleteResult delete_message(message, operation=None, params=dict())`
+</If>
+
 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.
 </If>
 
-<If lang="java">
+<If lang="java,python">
 ##### 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)`
 </If>
 
+<If lang="python">
+`UpdateDeleteResult append_message(message, operation=None, params=dict())`
+</If>
+
 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.
 </If>
 
-<If lang="java">
+<If lang="java,python">
 ##### 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<Message> getMessageVersions(String serial, Param[] params)`
 </If>
 
+<If lang="python">
+`PaginatedResult get_message_versions(serial_or_message, **params)`
+</If>
+
 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.
 </If>
 
-<If lang="java">
+<If lang="java,python">
 ##### 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.

src/pages/docs/messages/updates-deletes.mdx

@@ -163,6 +163,21 @@ channel.updateMessage(message, operation, new Callback<UpdateDeleteResult>() {
 });
 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")
+```
 </Code>
 
 #### Returns
@@ -332,6 +347,21 @@ channel.deleteMessage(message, operation, new Callback<UpdateDeleteResult>() {
 });
 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")
+```
 </Code>
 
 #### 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)
+```
 </Code>
 
 ## Get message versions <a id="versions"/>
@@ -664,6 +723,17 @@ String serial = "0123456789-001@abcdefghij:001";
 PaginatedResult<Message> 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");
+```
 </Code>
 
 ## Message version structure <a id="version-structure"/>