[#420][#422] present appropriate iRODSAccess.codes, in sorted order

(The sorting was an issue only in Python2, where the dict structure
doesn't maintain keys in the order introduced.)

For added convenience, we also add some smarts to the iRODSAccess
class, giving it the ability to function as a dictionary:

    iRODSAccess.keys() -> ['null', ... 'own']
    iRODSAccess['own'] -> 1200.

A new iRODSSession property, available_permissions, returns either
this class or the legacy _iRODSAccess_pre_4_3_0, thus

    session.available_permissions.keys()

returns a list of the permission strings (sorted according to the
numeric value, aka privilege level) which are applicable for the
connected server.

Author: d-w-moore

README.rst

@@ -1108,6 +1108,32 @@ users (those whose User.type is 'rodsadmin' or 'rodsuser'). The empty group ('em
 members, so it doesn't show up in our final list.
 
 
+iRODS Permissions (ACLs)
+------------------------
+
+The :code:`iRODSAccess` class offers a convenient dictionary interface mapping iRODS permission
+strings to the corresponding integer codes:
+
+>>> from irods.access import iRODSAccess
+>>> iRODSAccess.keys()
+['null', 'read_metadata', 'read_object', 'create_metadata', 'modify_metadata', 'delete_metadata', 'create_object', 'modify_object', 'delete_object', 'own']
+>>> WRITE = iRODSAccess.to_int('modify_object')
+
+Armed with that, we can then query on all data objects with ACL's that allow our user to write them:
+
+>>> from irods.models import (DataObject, User, DataAccess)
+>>> data_objects_writable = list(session.query(DataObject, User, DataAccess).filter(User.name == session.username,  DataAccess.type >= WRITE))
+
+Finally, we can also access the list of permissions available through a given session object via the :code:`available_permissions` property.
+Note that -- in keeping with changes in iRODS server 4.3 -- the permissions list will be longer, as appropriate, for session objects connected to
+the more recent servers; and also that the embedded spaces in some 4.2 permission strings will be replaced by underscores in 4.3 and later.
+
+>>> session.server_version
+(4, 2, 11)
+>>> session.available_permissions.items()
+[('null', 1000), ('read object', 1050), ('modify object', 1120), ('own', 1200)]
+
+
 Getting and setting permissions
 -------------------------------
 
@@ -1130,12 +1156,6 @@ If we then want to downgrade those permissions to read-only, we can do the follo
 A call to :code:`session.acls.get(c)` -- with :code:`c` being the result of :code:`sessions.collections.get(c[Collection.name])` --
 would then verify the desired change had taken place (as well as list all ACLs stored in the catalog for that collection).
 
-We can also query on access type using its numeric value, which will seem more natural to some:
-
->>> OWN = 1200; MODIFY = 1120 ; READ = 1050
->>> from irods.models import DataAccess, DataObject, User
->>> data_objects_writable = list(session.query(DataObject,DataAccess,User)).filter(User.name=='alice',  DataAccess.type >= MODIFY)
-
 One last note on permissions:  The older access manager, :code:`<session>.permissions`, produced inconsistent results when the :code:`get()`
 method was invoked with the parameter :code:`report_raw_acls` set (or defaulting) to :code:`False`.  Specifically, collections would exhibit the
 "non-raw-ACL" behavior of reporting individual member users' permissions as a by-product of group ACLs, whereas data objects would not.

irods/access.py

@@ -1,9 +1,27 @@
 import collections
+import copy
+import six
 
-class iRODSAccess(object):
+class _Access_LookupMeta(type):
+    def __getitem__(self, key): return self.codes[key]
+    def keys(self): return list(self.codes.keys())
+    def values(self): return list(self.codes[k] for k in self.codes.keys())
+    def items(self): return list(zip(self.keys(),self.values()))
 
-    codes = { key:value for key,value in dict(  # copied from iRODS server code:
-        null                 = 1000,            # server/core/include/irods/catalog_utilities.hpp
+class iRODSAccess(six.with_metaclass(_Access_LookupMeta)):
+
+    @classmethod
+    def to_int(cls,key):
+        return cls.codes[key]
+
+    @classmethod
+    def to_string(cls,key):
+        return cls.strings[key]
+
+    codes = collections.OrderedDict((key_,value_) for key_,value_ in sorted(dict(
+        # copied from iRODS source code in
+        #   ./server/core/include/irods/catalog_utilities.hpp:
+        null                 = 1000,
         execute              = 1010,
         read_annotation      = 1020,
         read_system_metadata = 1030,
@@ -21,7 +39,7 @@ class iRODSAccess(object):
         delete_token         = 1150,
         curate               = 1160,
         own                  = 1200
-    ).items() if key in (
+    ).items(),key=lambda _:_[1]) if key_ in (
             # These are copied from ichmod help text.
             'own',
             'delete_object',
@@ -34,9 +52,9 @@ class iRODSAccess(object):
             'read_metadata',
             'null'
         )
-    }
+    )
 
-    strings = collections.OrderedDict(sorted((number,string) for string,number in codes.items()))
+    strings = collections.OrderedDict((number,string) for string,number in codes.items())
 
     def __init__(self, access_name, path, user_name='', user_zone='', user_type=None):
         self.access_name = access_name
@@ -45,10 +63,31 @@ def __init__(self, access_name, path, user_name='', user_zone='', user_type=None
         self.user_zone = user_zone
         self.user_type = user_type
 
+    def copy(self, decanonicalize = False):
+        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
+        return other
+
     def __repr__(self):
         object_dict = vars(self)
         access_name = self.access_name.replace(' ','_')
         user_type_hint = ("({user_type})" if object_dict.get('user_type') is not None else "").format(**object_dict)
         return "<iRODSAccess {0} {path} {user_name}{1} {user_zone}>".format(access_name,
                                                                             user_type_hint,
                                                                             **object_dict)
+
+class _iRODSAccess_pre_4_3_0(iRODSAccess):
+    codes = collections.OrderedDict(
+        (key.replace('_',' '),value) for key,value in iRODSAccess.codes.items() if key in (
+            'own',
+            'write', 'modify_object',
+            'read', 'read_object',
+            'null'
+        ))
+    strings = collections.OrderedDict((number,string) for string,number in codes.items())

irods/manager/access_manager.py

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

irods/session.py

@@ -58,6 +58,15 @@ def auth_file (self):
     # method has a default parameter of report_raw_acls = True, so it enumerates
     # ACLs exactly in the manner of "ils -A".
 
+    @property
+    def available_permissions(self):
+        from irods.access import (iRODSAccess,_iRODSAccess_pre_4_3_0)
+        try:
+            self.__access
+        except AttributeError:
+            self.__access = _iRODSAccess_pre_4_3_0 if self.server_version < (4,3) else iRODSAccess
+        return self.__access
+
     @property
     def acls(self):
         class ACLs(self.permissions.__class__):

irods/test/access_test.py

@@ -80,6 +80,27 @@ def test_set_inherit_acl(self):
         c = self.sess.collections.get(self.coll_path)
         self.assertFalse(c.inheritance)
 
+    def test_available_permissions__420_422(self):
+        # Cycle through access levels (strings available via session.available_permissions) and test, with
+        # a string compare, that the "set" access level matches the "get" access level.
+        user = data = None
+        try:
+            user = self.sess.users.create('bob','rodsuser')
+            data = self.sess.data_objects.create('{}/obj_422'.format(helpers.home_collection(self.sess)))
+            permission_strings = self.sess.available_permissions.keys()
+            for perm in permission_strings:
+                access = iRODSAccess(perm, data.path, 'bob')
+                self.sess.acls.set( access )
+                a = [acl for acl in self.sess.acls.get( data ) if acl.user_name == 'bob']
+                if perm == 'null':
+                    self.assertEqual(len(a),0)
+                else:
+                    self.assertEqual(len(a),1)
+                    self.assertEqual(access.access_name,a[0].access_name)
+        finally:
+            if user: user.remove()
+            if data: data.unlink(force=True)
+
     def test_set_inherit_and_test_sub_objects (self):
         DEPTH = 3
         OBJ_PER_LVL = 1