add true ACLOperation/iRODSAccess canonicalization for api calls and comparison

Author: d-w-moore

README.md

@@ -2142,39 +2142,18 @@ indeed are subclassed from them as well, allowing intermixed sequences to be
 sorted; however, care should be taken to normalize the objects before comparisons
 or for related uses of the 'in' operator:
 ```py
-normalize = lambda acl: acl.copy(decanonicalize=True, implied_zone='tempZone')
+normalize = lambda acl: acl.copy(decanonicalize=-1, implied_zone='tempZone')
 acls = sorted(
     [
         iRODSAccess('read object', '/tempZone/home/alice', 'bob', 'tempZone'),
         ACLOperation('write', 'rods'),
         ACLOperation('read', 'bob'),
-    ], 
+    ],
     key=normalize
 )
 print(normalize(acls[0]) == normalize(acls[1]))
 ```
 
-Thus, for example:
-```py
-ACLOperation('read','public') in sess.acls.get(object)
-```
-is a valid operation, so that an application that tends to cache object
-permissions client-side might use such checks in optimizing atomic ACL
-requests against the inclusion of any redundant ACL operations.
-
-For purposes of sorting, a `__lt__` operator is also defined that would
-allow sorting of lists of `iRODSAccess`, `ACLOperations`, or the two intermixed:
-```py
-perms_list=[
-    ACLOperation('read', 'bob'),
-    iRODSAccess('read', '/tempZone/home/alice', 'alice')
-]
-print(sorted(perms_list))
-```
-
-and, as always, a sort key may be used for custom sorting; for example,
-the following sorts the objects simply by ascending numerical value of the access:
-```py
 perms = sorted(
     [
         ACLOperation('read', 'bob'),

irods/access.py

@@ -123,16 +123,44 @@ def __hash__(self):
         return hash((self.access_name, iRODSPath(self.path), self.user_name, self.user_zone))
 
     def copy(self, decanonicalize=False, implied_zone=''):
+        """
+        Create a copy of the object, possibly in a normalized form.
+
+        Args:
+            decanonicalize: Whether to modify to access_name field to a more human (1/True) or more standard (-1) form 
+                If the former, then one-word style is favored, ie "read" and "write".  If the latter, the new access_name
+                will be more machine-friendly for operators __lt__ (for sorting) and __eq__ (for equivalence or use with 'in').
+            implied_zone: If a nonzero-length name, compare this against the zone_name field of the old object and force the zone_name to
+                zero-length in the new object.
+
+        Returns:
+            The new copy
+        """
         other = copy.deepcopy(self)
 
-        if decanonicalize:
-            replacement_string = {
+        access_name = self.access_name
+
+        if decanonicalize == 1:
+            if (new_access_name := {
                 "read object": "read",
                 "read_object": "read",
                 "modify object": "write",
                 "modify_object": "write",
-            }.get(self.access_name)
-            other.access_name = replacement_string if replacement_string is not None else self.access_name
+            }.get(access_name)) != None: access_name = new_access_name
+        elif decanonicalize == -1:
+            # Canonicalize, ie. change out old access_name for an unambiguous "standard" value.
+            access_name = access_name.replace(" ","_")
+            if (new_access_name := {
+                "read": "read_object",
+                "write": "modify_object",
+            }.get(access_name)) != None: access_name = new_access_name
+        elif decanonicalize == 0:
+            pass
+        else:
+            msg = "Improper value for 'decanonicalize' parameter"
+            raise RuntimerError(msg)
+
+        other.access_name = access_name
 
         # Useful if we wish to force an explicitly specified local zone to an implicit zone spec in the copy, for equality testing:
         if '' != implied_zone == other.user_zone:
@@ -203,6 +231,9 @@ def __repr__(self):
     **{key: iRODSAccess.codes[_ichmod_synonym_mapping[key]] for key in _ichmod_synonym_mapping},
 }
 
+canonical_permissions = dict(
+    (k,v) for k,v in all_permissions.items() if ' ' not in k and k not in ('read','write')
+)
 
 class _deprecated:
     class _iRODSAccess_pre_4_3_0(_iRODSAccess_base):

irods/manager/access_manager.py

@@ -174,7 +174,7 @@ def set(self, acl, recursive=False, admin=False, **kw):
         zone_ = acl.user_zone
         if acl.access_name.endswith("inherit"):
             zone_ = userName_ = ""
-        acl = acl.copy(decanonicalize=True)
+        acl = acl.copy(decanonicalize=-1)
         message_body = ModAclRequest(
             recursiveFlag=int(recursive),
             accessLevel=f"{prefix}{acl.access_name}",

irods/test/access_test.py

@@ -515,7 +515,7 @@ def test_atomic_acls__issue_505(self):
             )
 
             def normalize(access):
-                return access.copy(decanonicalize=True, implied_zone=ses.zone)
+                return access.copy(decanonicalize=-1, implied_zone=ses.zone)
 
             accesses = [normalize(acl) for acl in ses.acls.get(self.coll)]