[#364][#365] test and documentation for admin_KW in metadata APIs

Author: d-w-moore

README.rst

@@ -411,6 +411,27 @@ of the (type of) catalog object they once annotated:
 >>> len(list( session.query(ResourceMeta) ))
 0
 
+When altering a fetched iRODSMeta, we must copy it first to avoid errors, due to the fact the reference
+is cached by the iRODS object reference.  A shallow copy is sufficient:
+
+>>> meta = album.metadata.items()[0]
+>>> meta.units
+'quid'
+>>> import copy; meta = copy.copy(meta); meta.units = 'pounds sterling'
+>>> album.metadata[ meta.name ] = meta
+
+Fortunately, as of PRC >= 1.1.4, we can simply do this instead:
+
+>>> album.metadata.set( meta )
+
+In versions of iRODS 4.2.12 and later, we can also do:
+
+>>> album.metadata.set( meta, **{kw.ADMIN_KW: ''} )
+
+or even:
+
+>>> album.metadata(admin = True)[meta.name] = meta
+
 
 Atomic operations on metadata
 -----------------------------

irods/meta.py

@@ -8,6 +8,14 @@ def __init__(self, name, value, units=None, avu_id=None):
         self.value = value
         self.units = units
 
+    def __eq__(self, other):
+        return tuple(self) == tuple(other)
+
+    def __iter__(self):
+        yield self.name
+        yield self.value
+        if self.units: yield self.units
+
     def __repr__(self):
         return "<iRODSMeta {avu_id} {name} {value} {units}>".format(**vars(self))
 

irods/test/meta_test.py

@@ -8,6 +8,8 @@
 from irods.manager.metadata_manager import InvalidAtomicAVURequest
 from irods.models import (DataObject, Collection, Resource)
 import irods.test.helpers as helpers
+import irods.keywords as kw
+from irods.session import iRODSSession
 from six.moves import range
 from six import PY3
 
@@ -218,6 +220,41 @@ def test_remove_obj_meta(self):
         assert len(meta) == 0
 
 
+    def test_metadata_manipulations_with_admin_kw__364__365(self):
+        try:
+            d = user = None
+            adm = self.sess
+            # Create a rodsuser, and a session for that roduser.
+            user = adm.users.create ( 'bobby','rodsuser' )
+            user.modify('password','bpass')
+            with iRODSSession (port=adm.port,zone=adm.zone,host=adm.host, user=user.name,password='bpass') as ses:
+                # Create a data object owned by the rodsuser.  Set AVUs in various ways and guarantee each attempt
+                # has the desired effect.
+                d = ses.data_objects.create('/{adm.zone}/home/{user.name}/testfile'.format(**locals()))
+
+                d.metadata.set('a','aa','1')
+                self.assertIn(('a','aa','1'), d.metadata.items())
+
+                d.metadata.set('a','aa')
+                self.assertEqual([('a','aa')], [tuple(_) for _ in d.metadata.items()])
+
+                d.metadata['a'] = iRODSMeta('a','bb')
+                self.assertEqual([('a','bb')], [tuple(_) for _ in d.metadata.items()])
+
+                # Now the admin does two AVU-set operations.  A successful test of these operations' success
+                # includes that both ('x','y') has been added and ('a','b','c') has overwritten ('a','bb').
+
+                da = adm.data_objects.get(d.path)
+                da.metadata.set('a','b','c',**{kw.ADMIN_KW:''})
+                da.metadata(admin = True)['x'] = iRODSMeta('x','y')
+                d = ses.data_objects.get(d.path) # assure metadata are not cached
+                self.assertEqual(set([('x','y'), ('a','b','c')]),
+                                 set(tuple(_) for _ in d.metadata.items()))
+        finally:
+            if d: d.unlink(force=True)
+            if user: user.remove()
+
+
     def test_add_coll_meta(self):
         # add metadata to test collection
         self.sess.metadata.add(Collection, self.coll_path,