readme -atomic ACLs

Author: d-w-moore

README.md

@@ -2118,6 +2118,34 @@ membership, this can be achieved with another query.
 `<session>.permissions` was therefore removed in v2.0.0
 in favor of `<session>.acls`.
 
+Atomic ACLs
+-----------
+
+A list of permissions may be added to an object atomically using
+the AccessManager's apply_atomic_operations method:
+```
+from irods.access import ACLOperation
+from irods.helpers import home_collection
+session = irods.helpers.make_session()
+myCollection = session.collections.create(f"{home_collection(session).path}/newCollection")
+
+session.acls.apply_atomic_operations(myCollection.path, 
+   *[ACLOperation("read", "public"),
+     ACLOperation("write", "bob", "otherZone")
+    ])
+```
+ACLOperation objects form a linear order with iRODSAccess objects, and
+indeed are subclassed from them as well, allowing equivalency testing:
+
+Thus, for example:
+```
+ACLOperation('read','public') in sess.acls.get(object)
+```
+is a valid operation. Consequently, any client application that habitually
+caches object permissions could use similar code to check new ACLOperations against the cache
+and conceivably be able to optimize size of an atomic ACLs request by eliminating
+any ACLOperations that might have been redundant.
+
 Quotas (v2.0.0)
 ---------------
 

irods/access.py

@@ -5,6 +5,22 @@
 from irods.path import iRODSPath
 
 
+_ichmod_listed_permissions = (
+            "own",
+            "delete_object",
+            "write",
+            "modify_object",
+            "create_object",
+            "delete_metadata",
+            "modify_metadata",
+            "create_metadata",
+            "read",
+            "read_object",
+            "read_metadata",
+            "null",
+            )
+
+
 class _Access_LookupMeta(type):
     def __getitem__(self, key):
         return self.codes[key]
@@ -55,22 +71,7 @@ def to_string(cls, key):
             ).items(),
             key=lambda _: _[1],
         )
-        if key_
-        in (
-            # These are copied from ichmod help text.
-            "own",
-            "delete_object",
-            "write",
-            "modify_object",
-            "create_object",
-            "delete_metadata",
-            "modify_metadata",
-            "create_metadata",
-            "read",
-            "read_object",
-            "read_metadata",
-            "null",
-        )
+        if key_ in _ichmod_listed_permissions
     )
 
     strings = collections.OrderedDict((number, string) for string, number in codes.items())
@@ -175,6 +176,20 @@ def __lt__(self, other):
     def __repr__(self):
         return f"<ACLOperation {self.access_name} {self.user_name} {self.user_zone}>"
 
+
+(_ichmod_synonym_mapping := {
+            # syn : canonical
+            "write": "modify_object",
+            "read":  "read_object"
+        }).update(
+            (key.replace("_"," "),key) for key in iRODSAccess.codes.keys())
+
+
+all_permissions = { **iRODSAccess.codes,
+                    **{key:iRODSAccess.codes[_ichmod_synonym_mapping[key]]
+                    for key in _ichmod_synonym_mapping}}
+
+
 class _iRODSAccess_pre_4_3_0(iRODSAccess):
     codes = collections.OrderedDict(
         (key.replace("_", " "), value)