doc updates, review and ruff changes, others as follows:

 - add true ACLOperation/iRODSAccess canonicalization for api calls and comparison

 - hash function for ACLOperation

 - extra normalizer method "normal" and consistent eq/hash semantics for use as dict keys and/or set members.

Author: d-w-moore

README.md

@@ -2118,32 +2118,65 @@ membership, this can be achieved with another query.
 `<session>.permissions` was therefore removed in v2.0.0
 in favor of `<session>.acls`.
 
-Atomic ACLs
------------
+Atomically setting permissions
+------------------------------
 
 A list of permissions may be added to an object atomically using
-the AccessManager's apply_atomic_operations method:
-```
+the AccessManager's `apply_atomic_operations` method:
+```py
 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")
+myCollection = session.collections.create(f"{home_collection(session)}/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 equivalence comparisons and
+also permitting intermixed sequences to be sorted (using the `__lt__` method
+if no sort `key` parameter is given).
+
+Care should be taken however to normalize the objects before such comparisons
+and sorting, and with connected uses of the `in` operator (which leverages `__eq__`).
+
+The following code sorts the objects based on their lexical order starting with the
+normalized `access_name`, which serves to group identical permissions together:
+```py
+from irods.access import *
+import irods.helpers
+acls = [
+    iRODSAccess('read_object', '/tempZone/home/alice', 'bob', 'tempZone'),
+    ACLOperation('write', 'rods'),
+    ACLOperation('read', 'bob'),
+]
 
-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:
+session = irods.helpers.make_session()
+N = lambda acl: acl.normalize(local_zone=session.zone)
 
-Thus, for example:
+print(N(acls[0]) == N(acls[2]))
+acls.sort(key=N)
+print(N(iRODSAccess('read', '', 'bob')) in map(N, acls))
 ```
-ACLOperation('read','public') in sess.acls.get(object)
+
+If strict order of permissions is desired, we can use code such as the following:
+```py
+from irods.access import *
+from pprint import pp
+pp(sorted(
+    [
+        ACLOperation('read', 'bob' ),
+        ACLOperation('own', 'rods'),
+        ACLOperation('read_object', 'alice')
+    ],
+    key=lambda acl: (all_permissions[acl.access_name], acl.normalize())
+))
 ```
-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 ACLOperations.
 
 Quotas (v2.0.0)
 ---------------

irods/access.py

@@ -2,10 +2,8 @@
 import copy
 from irods.collection import iRODSCollection
 from irods.data_object import iRODSDataObject
-from irods.path import iRODSPath
 
-
-_ichmod_listed_permissions = (
+_permissions = (
     "own",
     "delete_object",
     "write",
@@ -22,46 +20,45 @@
 
 
 class _Access_LookupMeta(type):
-
     @staticmethod
     def _codes():
         return collections.OrderedDict(
             (key_, value_)
             for key_, value_ in sorted(
-                dict(
-                    # copied from iRODS source code in
+                {
+                    # adapted from iRODS source code in
                     #   ./server/core/include/irods/catalog_utilities.hpp:
-                    null=1000,
-                    execute=1010,
-                    read_annotation=1020,
-                    read_system_metadata=1030,
-                    read_metadata=1040,
-                    read_object=1050,
-                    write_annotation=1060,
-                    create_metadata=1070,
-                    modify_metadata=1080,
-                    delete_metadata=1090,
-                    administer_object=1100,
-                    create_object=1110,
-                    modify_object=1120,
-                    delete_object=1130,
-                    create_token=1140,
-                    delete_token=1150,
-                    curate=1160,
-                    own=1200,
-                ).items(),
+                    "null": 1000,
+                    "execute": 1010,
+                    "read_annotation": 1020,
+                    "read_system_metadata": 1030,
+                    "read_metadata": 1040,
+                    "read_object": 1050,
+                    "write_annotation": 1060,
+                    "create_metadata": 1070,
+                    "modify_metadata": 1080,
+                    "delete_metadata": 1090,
+                    "administer_object": 1100,
+                    "create_object": 1110,
+                    "modify_object": 1120,
+                    "delete_object": 1130,
+                    "create_token": 1140,
+                    "delete_token": 1150,
+                    "curate": 1160,
+                    "own": 1200,
+                }.items(),
                 key=lambda _: _[1],
             )
-            if key_ in _ichmod_listed_permissions
+            if key_ in _permissions
         )
 
     @property
-    def codes(metaclass_target):
-        return metaclass_target._codes()
+    def codes(cls):
+        return cls._codes()
 
     @property
-    def strings(metaclass_target):
-        return collections.OrderedDict((number, string) for string, number in metaclass_target._codes().items())
+    def strings(cls):
+        return collections.OrderedDict((number, string) for string, number in cls._codes().items())
 
     def __getitem__(self, key):
         return self.codes[key]
@@ -102,37 +99,95 @@ def __init__(self, access_name, path, user_name, user_zone, user_type):
         self.user_type = user_type
 
     def __lt__(self, other):
-        return (self.access_name, self.user_name, self.user_zone, iRODSPath(self.path)) < (
+        return (self.access_name, self.user_name, self.user_zone, str(self.path)) < (
             other.access_name,
             other.user_name,
             other.user_zone,
-            iRODSPath(other.path),
+            str(other.path),
         )
 
     def __eq__(self, other):
         return (
             self.access_name == other.access_name
-            and iRODSPath(self.path) == iRODSPath(other.path)
+            and str(self.path) == str(other.path)
             and self.user_name == other.user_name
             and self.user_zone == other.user_zone
         )
 
     def __hash__(self):
-        return hash((self.access_name, iRODSPath(self.path), self.user_name, self.user_zone))
+        return hash((self.access_name, str(self.path), self.user_name, self.user_zone))
+
+    def normalize(self, local_zone=""):
+        """
+        Create a normalized version of the object for comparison in sorting or determining equivalence.
+
+        Args:
+            local_zone: the name of the home zone, if any, in which client user directly authenticates.
+                The purpose is zone name normalization; if this parameter is a nonzero-length string which
+                matches the zone_name in the source object, the copy will contain a null zone_name field.
+
+        Returns:
+            The normalized copy of the source object.  In practice, this will be an ACLOperation or iRODSAccess
+            object, according to the type of the source object.
+        """
+        normalized_form = self.copy(decanonicalize=-1, implied_zone=local_zone)
+        normalized_form.path = ""
+        return normalized_form
 
     def copy(self, decanonicalize=False, implied_zone=''):
+        """
+        Create a copy of the object, possibly in a normalized form.
+
+        Args:
+            decanonicalize: Whether to modify the access_name field to a more human-readable form
+                (when 1 or True) or a more standard form (when -1).  If the former, then a more
+                organic style is favored, i.e.  "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').  If equal to 0 (or False), no adjustment
+                is done.
+            implied_zone: If a nonzero-length name, compare this against the zone_name field of the
+                old object, and if they match, force the zone_name to zero-length in the new object.
+
+        Returns:
+            A copy of the invoking object, normalized if requested.
+
+        Raises:
+            RuntimeError: if decanonicalize parameter is not one of {-1,0,False,1,True}.
+        """
         other = copy.deepcopy(self)
 
-        if decanonicalize:
-            replacement_string = {
-                "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
+        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(access_name)
+            ) is not 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)
+            ) is not None:
+                access_name = new_access_name
+        elif decanonicalize == 0:
+            pass
+        else:
+            msg = "Improper value for 'decanonicalize' parameter"
+            raise RuntimeError(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:
+        # 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:
             other.user_zone = ''
 
@@ -146,14 +201,32 @@ def __repr__(self):
 
 
 class iRODSAccess(_iRODSAccess_base, metaclass=_Access_LookupMeta):
-    def __init__(self, access_name, path, user_name="", user_zone="", user_type=None):
+    """
+    Represents an ACL in iRODS.
+
+    An instance of this class functions as a data container to convey information to the iRODS
+    server (in the `set` call) and back again to the client again (in the `get` call).
+    """
+
+    def __init__(self, access_name, path, user_name="", user_zone="", user_type=None):  # noqa: D107
         self.codes = self.__class__.codes
         self.strings = self.__class__.strings
         super().__init__(access_name, path, user_name, user_zone, user_type)
 
 
 class ACLOperation(iRODSAccess):
-    def __init__(self, access_name: str, user_name: str = "", user_zone: str = ""):
+    """
+    Represents an operation to be performed in iRODS' atomic ACL api.
+
+    Similar to its base class, iRODSAccess, this class names an ACL to be set on an object.
+    It differs, however, in that it forgoes option to store a logical object path.  (In the atomic
+    API call, there is always a single logical path to which all such operations apply, thus
+    it is appropriate that the path parameter is in a location separate from the operations.)
+    """  # noqa: D400
+
+    # ruff: noqa: D105 on
+
+    def __init__(self, access_name: str, user_name: str = "", user_zone: str = ""):  # noqa: D107
         super().__init__(
             access_name=access_name,
             path="",
@@ -172,6 +245,16 @@ def __eq__(self, other):
             other.user_zone,
         )
 
+    def __hash__(self):
+
+        # Hash in a way consistent with an iRODSAccess having path "".
+        return hash((
+            self.access_name,
+            "",  # path
+            self.user_name,
+            self.user_zone,
+        ))
+
     def __lt__(self, other):
         return (
             self.access_name,
@@ -186,19 +269,20 @@ def __lt__(self, other):
     def __repr__(self):
         return f"<ACLOperation {self.access_name} {self.user_name} {self.user_zone}>"
 
+    # ruff: noqa: D105 off
+
 
 (
-    _ichmod_synonym_mapping := {
-        # syn : canonical
+    _synonym_mapping := {
         "write": "modify_object",
         "read": "read_object",
     }
-).update((key.replace("_", " "), key) for key in iRODSAccess.codes.keys())
+).update((key.replace("_", " "), key) for key in iRODSAccess.codes)
 
 
 all_permissions = {
     **iRODSAccess.codes,
-    **{key: iRODSAccess.codes[_ichmod_synonym_mapping[key]] for key in _ichmod_synonym_mapping},
+    **{key: iRODSAccess.codes[_synonym_mapping[key]] for key in _synonym_mapping},
 }
 
 

irods/exception.py

@@ -1,14 +1,16 @@
 # if you're copying these from the docs, you might find the following regex helpful:
 # s/\(\w\+\)\s\+\(-\d\+\)/class \1(SystemException):\r    code = \2/g
 
-
 import errno
 import numbers
 import os
 import sys
 from typing import Dict
 
 
+# ruff: noqa: N801 D101 off
+
+
 class PycommandsException(Exception):
     pass
 
@@ -2124,3 +2126,6 @@ class PAM_AUTH_PASSWORD_FAILED(PAMException):
 
 class PAM_AUTH_PASSWORD_INVALID_TTL(PAMException):
     code = -994000
+
+
+# ruff: noqa: N801 D101 on