[_SQ] document sort key fns

Author: d-w-moore

irods/manager/data_object_manager.py

@@ -9,6 +9,7 @@
 from irods.models import DataObject, Collection
 from irods.manager import Manager
 from irods.manager._internal import _api_impl, _logical_path
+
 from irods.message import (
     iRODSMessage,
     FileOpenRequest,
@@ -30,6 +31,8 @@
     chunks,
     irods_dirname,
     irods_basename,
+    REPLICA_NUMBER_SORT_KEY_FN,
+    REPLICA_FITNESS_SORT_KEY_FN,
 )
 import irods.client_configuration as client_config
 import irods.keywords as kw
@@ -258,17 +261,26 @@ def _download(self, obj_path, local_path, num_threads, updatables=(), **options)
                         f.write(chunk)
                         do_progress_updates(updatables, len(chunk))
 
-    def get(self, path, local_path=None, num_threads=DEFAULT_NUMBER_OF_THREADS, updatables=(), **options):
+    def get(self,
+        path,
+        local_path=None,
+        num_threads=DEFAULT_NUMBER_OF_THREADS,
+        updatables=(),
+        replica_sort_function = None,
+        **options):
         """
         Get a reference to the data object at the specified `path'.
 
         Only download the object if the local_path is a string (specifying
         a path in the local filesystem to use as a destination file).
+
+        If replica_sort_function is not specified, the replicas list contained in the returned
+        object will be sorted according to replica number (REPLICA_NUMBER_SORT_KEY_FN) in PRC < v4
+        or by general fitness to be considered as a current data copy (REPLICA_FITNESS_SORT_KEY_FN).
+        in PRC >= v4.  For those definitions, see irods/data_object.py .
         """
         parent = self.sess.collections.get(irods_dirname(path))
 
-        replica_sort_function = options.pop('replica_sort_function', None)
-
         # TODO: optimize
         if local_path:
             self._download(path, local_path, num_threads=num_threads, updatables=updatables, **options)