Confirmation is now optional. (#270)

* Confirmation is now optional.

AB#9779

Author: eccles

README.rst

@@ -84,22 +84,34 @@ You can then use the examples code to create assets (see examples directory):
             # it does not start with arc_
         }
         #
-        # The first argument are the attributes of the asset
-        # The second argument is wait for confirmation:
-        #   If @confirm@ is True then this function will not
-        #   return until the asset is confirmed and ready
-        #   to accept events (or an error occurs)
+        # There are 3 alternatives
         #
+        # 1. Create the asset:
+        #    The first argument is the attributes of the asset
+        return arch.assets.create(attrs=attrs)
+        #
+        # 2. alternatively one can wait for the asset to be confirmed in the
+        #    immutable store.
+        #    The second argument is wait for confirmation:
+        #      If @confirm@ is True then this function will not
+        #      return until the asset is confirmed.
+        #
+        # Confirmation guarantees that 3rd parties can retrieve and cryptographically
+        # verify your Assets, which can take a few seconds to propagate. It is typically
+        # not necessary to wait unless your workflow involves near-real-time
+        # communication with 3rd parties and the 3rd party needs immediate cryptographic
+        # verification of your new Asset.
         return arch.assets.create(attrs=attrs, confirm=True)
-        # alternatively if some work can be done whilst the asset is confirmed then this call can be
-        # replaced by a two-step alternative:
+        #
+        # 3. lastly if some work can be done whilst the asset is confirmed then this call
+        # can be replaced by a two-step alternative:
 
-        # asset = arch.assets.create(props=props, attrs=attrs, confirm=False)
+        asset = arch.assets.create(props=props, attrs=attrs)
 
         # ... do something else here
         # and then wait for confirmation
 
-        # self.arch.assets.wait_for_confirmation(asset['identity']))
+        return arch.assets.wait_for_confirmation(asset['identity']))
 
 
     def main():
@@ -238,7 +250,12 @@ Each step consists of control parameters (specified in the 'step' dictionary) an
 the yaml representation of the request body for an asset or event.
 
 The confirm: field is a control variable for the PythonSDK that ensures that the
-asset or event is confirmed before returning.
+asset or event is confirmed before returning. This is optional and is only required
+3rd parties need to immediately retrieve and cryptographically
+verify your Assets, which can take a few seconds to propagate. It is typically
+not necessary to wait unless your workflow involves near-real-time
+communication with 3rd parties and the 3rd party needs instant cryptographic
+verification of your new Asset.
 
 .. note::
 
@@ -276,7 +293,6 @@ asset or event is confirmed before returning.
           radioactive: "true"
           radiation_level: "0"
           weight: "0"
-        confirm: true
 
       # setup the radiation bags to have a varing amount of radiactive waste
       # note the values to the events.create method are string representations of boolean
@@ -294,7 +310,6 @@ asset or event is confirmed before returning.
         asset_attributes:
           radiation_level: "3"
           weight: "1"
-        confirm: true
 
 Logging
 ========

archivist/assets.py

@@ -120,7 +120,7 @@ def create(
         *,
         props: "dict[str, Any]|None" = None,
         attrs: "dict[str, Any]|None" = None,
-        confirm: bool = True,
+        confirm: bool = False,
     ) -> Asset:
         """Create asset
 
@@ -143,7 +143,7 @@ def create(
         return self.create_from_data(data, confirm=confirm)
 
     def create_from_data(
-        self, data: "dict[str, Any]", *, confirm: bool = True
+        self, data: "dict[str, Any]", *, confirm: bool = False
     ) -> Asset:
         """Create asset
 
@@ -152,7 +152,7 @@ def create_from_data(
 
         Args:
             data (dict): request body of asset.
-            confirm (bool): if True wait for asset to be confirmed on DLT.
+            confirm (bool): if True wait for asset to be confirmed.
 
         Returns:
             :class:`Asset` instance
@@ -165,15 +165,15 @@ def create_from_data(
         return self.wait_for_confirmation(asset["identity"])
 
     def create_if_not_exists(
-        self, data: "dict[str, Any]", *, confirm: bool = True
+        self, data: "dict[str, Any]", *, confirm: bool = False
     ) -> "tuple[Asset, bool]":
         """
         Creates an asset and associated locations and attachments if asset
         does not already exist.
 
         Args:
             data (dict): request body of asset.
-            confirm (bool): if True wait for asset to be confirmed on DLT.
+            confirm (bool): if True wait for asset to be confirmed.
 
         A YAML representation of the data argument would be:
 
@@ -272,7 +272,7 @@ def create_if_not_exists(
     def wait_for_confirmation(self, identity: str) -> Asset:
         """Wait for asset to be confirmed.
 
-        Waits asset to be confirmed.
+        Waits for asset to be confirmed.
 
         Args:
             identity (str): identity of asset

archivist/events.py

@@ -297,7 +297,7 @@ def create(
         attrs: "dict[str, Any]",
         *,
         asset_attrs: "dict[str, Any]|None" = None,
-        confirm: bool = True,
+        confirm: bool = False,
     ) -> Event:
         """Create event
 
@@ -308,7 +308,7 @@ def create(
             props (dict): properties for this event.
             attrs (dict): attributes of created event.
             asset_attrs (dict): attributes of referenced asset.
-            confirm (bool): if True wait for event to be confirmed on DLT.
+            confirm (bool): if True wait for event to be confirmed.
 
         Returns:
             :class:`Event` instance
@@ -323,7 +323,7 @@ def create(
         )
 
     def create_from_data(
-        self, asset_id: str, data: "dict[str, Any]", *, confirm: bool = True
+        self, asset_id: str, data: "dict[str, Any]", *, confirm: bool = False
     ) -> Event:
         """Create event
 

archivist/notebooks/Check Asset Compliance using CURRENT OUTSTANDING Policy.ipynb

@@ -169,7 +169,6 @@
     "                \"arc_display_type\": \"Vault Door\",\n",
     "            },\n",
     "        },\n",
-    "        confirm=True,\n",
     "    )\n",
     "    print(\"DOOR:\", json_dumps(door, indent=4))\n",
     "    return door"
@@ -197,7 +196,6 @@
     "            \"arc_display_type\": \"Open\",\n",
     "            \"arc_correlation_value\": f\"{tag}\",\n",
     "        },\n",
-    "        confirm=True,\n",
     "    )\n",
     "    print(\"DOOR_OPENED:\", json_dumps(door_opened, indent=4))"
    ]
@@ -224,7 +222,6 @@
     "            \"arc_display_type\": \"Close\",\n",
     "            \"arc_correlation_value\": f\"{tag}\",\n",
     "        },\n",
-    "        confirm=True,\n",
     "    )\n",
     "    print(\"DOOR_CLOSED:\", json_dumps(door_closed, indent=4))"
    ]

archivist/notebooks/Check Asset Compliance using SINCE Policy.ipynb

@@ -164,7 +164,6 @@
     "            \"arc_description\": \"Traffic flow control light at A603 North East\",\n",
     "            \"arc_display_type\": \"Traffic Light\",\n",
     "        },\n",
-    "        confirm=True,\n",
     "    )\n",
     "    print(\"TRAFFIC_LIGHT:\", json_dumps(traffic_light, indent=4))\n",
     "    return traffic_light"
@@ -191,7 +190,6 @@
     "            \"arc_description\": \"Maintenance performed on traffic light\",\n",
     "            \"arc_display_type\": f\"Maintenance Performed {tag}\",\n",
     "        },\n",
-    "        confirm=True,\n",
     "    )\n",
     "    print(\"MAINTENANCE_PERFORMED:\", json_dumps(maintenance_performed, indent=4))"
    ]

archivist/notebooks/Create Artist and Album Release Info.ipynb

@@ -137,7 +137,7 @@
     "        \"artistid\": artistid,\n",
     "    }\n",
     "\n",
-    "    return arch.assets.create(attrs=attrs, confirm=True)"
+    "    return arch.assets.create(attrs=attrs)"
    ]
   },
   {

archivist/notebooks/Create Event with Verified Domain.ipynb

@@ -188,7 +188,7 @@
     "    # alternatively if some work can be done whilst the event is confirmed then this call can be\n",
     "    # replaced by a two-step alternative:\n",
     "\n",
-    "    # event = arch.events.create(asset[\"identity\"], props=props, attrs=attrs, confirm=False)\n",
+    "    # event = arch.events.create(asset[\"identity\"], props=props, attrs=attrs)\n",
     "\n",
     "    # ... do something else here\n",
     "    # and then wait for confirmation\n",
@@ -232,8 +232,7 @@
     "    # The first argument is the attributes of the asset\n",
     "    # The second argument is wait for confirmation:\n",
     "    #   If @confirm@ is True then this function will not\n",
-    "    #   return until the asset is confirmed and ready\n",
-    "    #   to accept events (or an error occurs)\n",
+    "    #   return until the asset is confirmed.)\n",
     "    return arch.assets.create(attrs=attrs, confirm=True)"
    ]
   },

archivist/runner.py

@@ -421,7 +421,6 @@ def __call__(self, config: "dict[str, Any]"):
                     "radiation_level": 0,
                     "weight": 0,
                 },
-                "confirm": True,
             }
         ]
         ```

archivist/tenancies.py

@@ -62,7 +62,7 @@ def __init__(self, archivist_instance: "Archivist"):
     def __str__(self) -> str:
         return f"TenanciesClient({self._archivist.url})"
 
-    def _identity(self, identity) -> str:
+    def _identity(self, identity: str) -> str:
         """Returns identity suitable for endpoint"""
         prefix, uuid = identity.split("/")
         if prefix == TENANCIES_PREFIX:

docs/features.rst

@@ -13,7 +13,7 @@ REST api (in any language):
     *  versioned package for the python 3.8,3.9,3.10,3.11,3.12 ecosystem.
     *  automatic confirmation of assets and events: just set **confirm=True** when
        creating the asset or event and a sophisticated retry and exponential backoff
-       algorithm will take care of everything.
+       algorithm will take care of everything (optional).
     *  **list()** method: one can easily get an iterable of assets or events that
        correspond to a particular signature. The list method is optimized for use in
        loop (for a in arch.assets.list():...) but can easily be converted to a list
@@ -31,6 +31,6 @@ REST api (in any language):
     *  easily extensible - obeys the open-closed principle of SOLID where new endpoints 
        can be implemented by **extending** the package as opposed to modifying it.
     *  fully unittested - 100% coverage.
-    *  code style managed and enforced using **pycodestyle**, **pylint** and **black**. 
+    *  code style managed and enforced using **ruff**, **pycodestyle**, **pylint** and **black**. 
 
 See the **examples/** directory for example code.