[#132,#322] data object put and create can raise an error rather than overwrite.

PUT will respect FORCE_FLAG_KW, to mimic iput; whereas create will now respect
the force=True option when requested.

Implemented two configuration settings which help to preserve compatibility with
existing applications for v3.1.1 release.  These can be set False for new
applications in which put() and create() are, by default, expected not to overwrite
existing data objects.

Author: d-w-moore

README.md

@@ -286,6 +286,24 @@ iRODS PUT API directly.  This is transparent to the caller, but an administrator
 should take note as this affects which policy enforcement points (PEPs) are executed
 on the iRODS server.
 
+Release v3.1.1 introduces the optional behavior of preventing a call to data object manager's `put()` or `create()`
+method from succeeding if the requested data path already exists.  This will become the default in some future release,
+but for now the following code can be used to enable it for the duration of
+an application's run:
+
+```python
+import irods.client_configuration as config
+# Prevent accidental data object overwrites in put() and create().
+config.data_objects.force_create_by_default = False
+config.data_objects.force_put_by_default = False
+```
+
+A more ad-hoc solution to defeat the "True" defaults is by passing `**{irods.keywords.FORCE_FLAG_KW:False}` among
+the options in an individual call to `put`, or using force=False in a call to `create`.
+
+Both solutions will be unnecessary, but still remain effective, when True-defaulting "force flag" style data overwrites
+become non-default behavior and/or deprecated in a future release.
+
 Parallel Transfer
 -----------------
 

irods/client_configuration/__init__.py

@@ -70,6 +70,8 @@ class DataObjects(iRODSConfiguration):
     __slots__ = (
         "auto_close",
         "allow_redirect",
+        "force_create_by_default",
+        "force_put_by_default",
     )
 
     def __init__(self):
@@ -86,6 +88,9 @@ def __init__(self):
         self.auto_close = False
         self.allow_redirect = False
 
+        self.force_create_by_default = True
+        self.force_put_by_default = True
+
 
 # #############################################################################
 #

irods/exception.py

@@ -24,6 +24,10 @@ class InvalidInputArgument(PycommandsException):
     pass
 
 
+class DataObjectExistsAtLogicalPath(PycommandsException):
+    pass
+
+
 class DataObjectDoesNotExist(DoesNotExist):
     pass
 

irods/manager/data_object_manager.py

@@ -35,6 +35,7 @@
 import irods.parallel as parallel
 from irods.parallel import deferred_call
 
+
 logger = logging.getLogger(__name__)
 
 _update_types = []
@@ -302,6 +303,24 @@ def get(
             raise ex.DataObjectDoesNotExist()
         return iRODSDataObject(self, parent, results)
 
+    @staticmethod
+    def _resolve_force_put_option(options, default_setting=None, true_value=""):
+        """If 'default_setting' is True or the force flag is already set in 'options', leave (or put) the flag there,
+        with the value set to the 'truth_value'.
+
+        If the result of this resolves as False for the force flag in the 'options' dict, we then choose to remove the flag
+        from `options`, since it is the flag's mere presence in the API call that achieves the forcing behavior.
+
+        For the same reason, we also count string values (even empty ones) as unconditionally True, since that is convention
+        for server APIs that use the FORCE_FLAG_KW.
+        """
+
+        force = options.setdefault(kw.FORCE_FLAG_KW, default_setting)
+        if force or isinstance(force, str):
+            options[kw.FORCE_FLAG_KW] = true_value
+        else:
+            del options[kw.FORCE_FLAG_KW]
+
     def put(
         self,
         local_path,
@@ -311,13 +330,20 @@ def put(
         updatables=(),
         **options
     ):
+        # Decide if a put option should be used and modify options accordingly.
+        self._resolve_force_put_option(
+            options, default_setting=client_config.data_objects.force_put_by_default
+        )
 
         if self.sess.collections.exists(irods_path):
             obj = iRODSCollection.normalize_path(
                 irods_path, os.path.basename(local_path)
             )
         else:
             obj = irods_path
+            if kw.FORCE_FLAG_KW not in options and self.exists(obj):
+                raise ex.OVERWRITE_WITHOUT_FORCE_FLAG
+        options.pop(kw.FORCE_FLAG_KW, None)
 
         with open(local_path, "rb") as f:
             sizelist = []
@@ -458,8 +484,28 @@ def parallel_put(
             updatables=updatables,
         )
 
-    def create(self, path, resource=None, force=False, **options):
-        options[kw.DATA_TYPE_KW] = "generic"
+    @staticmethod
+    def _call_thru(c):
+        return c() if callable(c) else c
+
+    def create(
+        self,
+        path,
+        resource=None,
+        force=client_config.getter("data_objects", "force_create_by_default"),
+        **options
+    ):
+        """
+        Create a new data object with the given logical path.
+
+        'resource', if provided, is the root node of a storage resource hierarchy where the object is preferentially to be created.
+        'force', when False, raises an DataObjectExistsAtLogicalPath if there is already a data object at the logical path specified.
+        """
+
+        if not self._call_thru(force) and self.exists(path):
+            raise ex.DataObjectExistsAtLogicalPath
+
+        options = {**options, kw.DATA_TYPE_KW: "generic"}
 
         if resource:
             options[kw.DEST_RESC_NAME_KW] = resource
@@ -470,9 +516,6 @@ def create(self, path, resource=None, force=False, **options):
             except AttributeError:
                 pass
 
-        if force:
-            options[kw.FORCE_FLAG_KW] = ""
-
         message_body = FileOpenRequest(
             objPath=path,
             createMode=0o644,