Query improvements: add SmartContractQueriesController.query()

examples/Cookbook.ipynb

@@ -26,7 +26,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [
     {
@@ -58,7 +58,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -74,7 +74,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 5,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -91,7 +91,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 6,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -113,7 +113,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 7,
    "metadata": {},
    "outputs": [
     {
@@ -139,7 +139,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [
     {
@@ -166,7 +166,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [
     {
@@ -199,7 +199,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [
     {
@@ -249,7 +249,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 11,
    "metadata": {},
    "outputs": [
     {
@@ -283,7 +283,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 12,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -301,7 +301,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 13,
    "metadata": {},
    "outputs": [
     {
@@ -341,7 +341,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 14,
    "metadata": {},
    "outputs": [
     {
@@ -380,7 +380,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 15,
    "metadata": {},
    "outputs": [
     {
@@ -415,7 +415,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 16,
    "metadata": {},
    "outputs": [
     {
@@ -450,7 +450,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 17,
    "metadata": {},
    "outputs": [
     {
@@ -497,7 +497,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 18,
    "metadata": {},
    "outputs": [
     {
@@ -536,7 +536,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": 19,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -555,7 +555,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": 20,
    "metadata": {},
    "outputs": [
     {
@@ -608,7 +608,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 21,
    "metadata": {},
    "outputs": [
     {
@@ -677,7 +677,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 21,
+   "execution_count": 22,
    "metadata": {},
    "outputs": [
     {
@@ -721,7 +721,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 22,
+   "execution_count": 23,
    "metadata": {},
    "outputs": [
     {
@@ -762,7 +762,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 23,
+   "execution_count": 24,
    "metadata": {},
    "outputs": [
     {
@@ -798,7 +798,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 24,
+   "execution_count": 25,
    "metadata": {},
    "outputs": [
     {
@@ -843,20 +843,19 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In order to create a contract query and run it (more details about **network providers** can be found below), do as follows:"
+    "In order to do a contract query against the network (more details about **network providers** can be found below), do as follows:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 25,
+   "execution_count": 26,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Return code: ok\n",
-      "Return data: [b'\\x05']\n"
+      "Return data (parsed): [b'\\x05']\n"
      ]
     }
    ],
@@ -868,16 +867,51 @@
     "query_runner = QueryRunnerAdapter(ProxyNetworkProvider(\"https://devnet-api.multiversx.com\"))\n",
     "\n",
     "query_controller = SmartContractQueriesController(query_runner)\n",
+    "\n",
+    "data_parts = query_controller.query(\n",
+    "    contract=contract.to_bech32(),\n",
+    "    function=\"getSum\",\n",
+    "    arguments=[],\n",
+    ")\n",
+    "\n",
+    "print(\"Return data (parsed):\", data_parts)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For finer control, first create a contract query, then run it and parse the outcome at a later time:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 56,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Return code: ok\n",
+      "Return data (raw): [b'\\x05']\n",
+      "Return data (parsed): [b'\\x05']\n"
+     ]
+    }
+   ],
+   "source": [
     "query = query_controller.create_query(\n",
     "    contract=contract.to_bech32(),\n",
     "    function=\"getSum\",\n",
     "    arguments=[],\n",
     ")\n",
     "\n",
     "response = query_controller.run_query(query)\n",
+    "data_parts = query_controller.parse_query_response(response)\n",
     "\n",
     "print(\"Return code:\", response.return_code)\n",
-    "print(\"Return data:\", response.return_data_parts)"
+    "print(\"Return data (raw):\", response.return_data_parts)\n",
+    "print(\"Return data (parsed):\", data_parts)"
    ]
   },
   {
@@ -1593,7 +1627,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.10.12"
   },
   "orig_nbformat": 4,
   "vscode": {

multiversx_sdk/core/address.py

@@ -101,8 +101,6 @@ def is_smart_contract(self) -> bool:
     # this will be removed in v1.0.0; it's here for compatibility reasons with the deprecated transaction builders
     # the transaction builders will also be removed in v1.0.0
     def serialize(self) -> bytes:
-        """This method is deprecated and will soon be removed. Also displays a deprecation warning when used."""
-        logger.warning("The `serialize()` method is deprecated and will soon be removed")
         return self.get_public_key()
 
 

multiversx_sdk/core/errors.py

@@ -59,3 +59,9 @@ def __init__(self, message: str) -> None:
 class ParseTransactionOutcomeError(Exception):
     def __init__(self, message: str) -> None:
         super().__init__(message)
+
+
+class SmartContractQueryError(Exception):
+    def __init__(self, return_code: str, message: str) -> None:
+        super().__init__(message)
+        self.return_code = return_code

multiversx_sdk/core/smart_contract_queries_controller.py

@@ -1,5 +1,6 @@
 from typing import Any, List, Optional, Protocol
 
+from multiversx_sdk.core.errors import SmartContractQueryError
 from multiversx_sdk.core.smart_contract_query import (
     SmartContractQuery, SmartContractQueryResponse)
 
@@ -13,6 +14,31 @@ class SmartContractQueriesController:
     def __init__(self, query_runner: IQueryRunner) -> None:
         self.query_runner = query_runner
 
+    def query(
+        self,
+        contract: str,
+        function: str,
+        arguments: List[bytes],
+        caller: Optional[str] = None,
+        value: Optional[int] = None
+    ):
+        query = self.create_query(
+            contract=contract,
+            function=function,
+            arguments=arguments,
+            caller=caller,
+            value=value
+        )
+
+        query_response = self.run_query(query)
+        self._raise_for_status(query_response)
+        return self.parse_query_response(query_response)
+
+    def _raise_for_status(self, query_response: SmartContractQueryResponse):
+        is_ok = query_response.return_code == "ok"
+        if not is_ok:
+            raise SmartContractQueryError(query_response.return_code, query_response.return_message)
+
     def create_query(
             self,
             contract: str,

multiversx_sdk/core/smart_contract_queries_controller_test.py

@@ -3,6 +3,7 @@
 import pytest
 
 from multiversx_sdk.adapters.query_runner_adapter import QueryRunnerAdapter
+from multiversx_sdk.core.codec import encode_unsigned_number
 from multiversx_sdk.core.smart_contract_queries_controller import \
     SmartContractQueriesController
 from multiversx_sdk.core.smart_contract_query import (
@@ -41,11 +42,11 @@ def test_create_query_with_arguments(self):
         query = self.controller.create_query(
             contract=contract,
             function=function,
-            arguments=[int.to_bytes(7), "abba".encode()]
+            arguments=[encode_unsigned_number(7), "abba".encode()]
         )
         assert query.contract == contract
         assert query.function == function
-        assert query.arguments == [int.to_bytes(7), "abba".encode()]
+        assert query.arguments == [encode_unsigned_number(7), "abba".encode()]
         assert query.caller is None
         assert query.value is None
 
@@ -100,3 +101,16 @@ def test_run_query_on_network(self):
         assert query_response.return_code == "ok"
         assert query_response.return_message == ""
         assert query_response.return_data_parts == [b'\x05']
+
+    @pytest.mark.networkInteraction
+    def test_query_on_network(self):
+        contract = "erd1qqqqqqqqqqqqqpgqsnwuj85zv7t0wnxfetyqqyjvvg444lpk7uasxv8ktx"
+        function = "getSum"
+
+        return_data_parts = self.controller.query(
+            contract=contract,
+            function=function,
+            arguments=[]
+        )
+
+        assert return_data_parts == [b'\x05']

pyproject.toml

@@ -7,7 +7,7 @@ allow-direct-references = true
 
 [project]
 name = "multiversx-sdk"
-version = "0.9.0"
+version = "0.9.1"
 authors = [
   { name="MultiversX" },
 ]