Added rights granting documentation

emdb-empiar · Dec 17, 2020 · 35b01de · 35b01de
1 parent 3ef2d84
commit 35b01de
Show file tree

Hide file tree

Showing 4 changed files with 81 additions and 20 deletions.
diff --git a/README.rst b/README.rst
@@ -22,17 +22,21 @@ How to use
 
 Please follow these steps:
 
-1. Create a JSON file according to the `schema <empiar_depositor/empiar_deposition.schema.json>`_. An `example <empiar_depositor/tests/deposition_json/working_example.json>`_ of such a file.
+1. Create a JSON file according to the `schema <empiar_depositor/empiar_deposition.schema.json>`_. An
+`example <empiar_depositor/tests/deposition_json/working_example.json>`_ of such a file.
 
-2. Download and install `ascp tool <http://downloads.asperasoft.com/connect2/>`_ and/or install globus-cli (supported version 1.7.0) with
+2. Download and install `ascp tool <http://downloads.asperasoft.com/connect2/>`_ and/or install globus-cli (supported
+version 1.7.0) with
 
    .. code:: bash
 
      pip install globus-cli==1.7.0
 
    Globus can be used as a separate upload option or as a fallback if Aspera fails.
 
-3. Set the environmental variable for EMPIAR transfer password to the one that EMPIAR team has provided you with. Please note that this is not the API token from 1) and is a separate password from the one that you create when registering EMPIAR user.
+3. Set the environmental variable for EMPIAR transfer password to the one that EMPIAR team has provided you with. Please
+note that this is not the API token from 1) and is a separate password from the one that you create when registering
+EMPIAR user.
 
    - On Linux and Mac OS X execute
 
@@ -57,15 +61,19 @@ Positional arguments:
 
 ``EMPIAR_TOKEN``
 ~~~~~~~~~~~~~~~~
-EMPIAR API token. You can generate it at `https://empiar.org/deposition/api_token <https://empiar.org/deposition/api_token>`_. Alternatively, instead of the token you can use your EMPIAR username and provide your password with **-p** optional argument (see below for more information).
+EMPIAR API token. You can generate it at
+`https://empiar.org/deposition/api_token <https://empiar.org/deposition/api_token>`_. Alternatively, instead of the
+token you can use your EMPIAR username and provide your password with **-p** optional argument (see below for more
+information).
 
 ``JSON_INPUT``
 ~~~~~~~~~~~~~~
 The location of the JSON with EMPIAR deposition information.
 
 ``DATA``
 ~~~~~~~~
-The location of the data that you would like to upload to EMPIAR. It should contain directories that correspond to the image set directories specified in the JSON file.
+The location of the data that you would like to upload to EMPIAR. It should contain directories that correspond to the
+image set directories specified in the JSON file.
 
 Optional arguments:
 +++++++++++++++++++
@@ -76,27 +84,45 @@ Show help message and exit
 
 ``-p PASSWORD, --password PASSWORD``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Use basic authentication (username + password) instead of token authentication. If no password is provided for this argument, then the user is prompted for a password.
+Use basic authentication (username + password) instead of token authentication. If no password is provided for this
+argument, then the user is prompted for a password.
 
 ``-a ASCP, --ascp ASCP``
 ~~~~~~~~~~~~~~~~~~~~~~~~
-The location of the ascp executable. By default it is installed in ~/.aspera/connect/bin directory on Linux machines, in ~/Applications/Aspera\\ Connect.app/Contents/Resources directory on Macs and in C:\\Users\\<username>\\AppData\\Local\\Programs\\Aspera\\Aspera Connect\\bin on Windows.
+The location of the ascp executable. By default it is installed in ~/.aspera/connect/bin directory on Linux machines,
+in ~/Applications/Aspera\\ Connect.app/Contents/Resources directory on Macs and in
+C:\\Users\\<username>\\AppData\\Local\\Programs\\Aspera\\Aspera Connect\\bin on Windows.
 
 ``-g GLOBUS, --globus GLOBUS``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Use Globus if Aspera is not specified or Aspera transfer fails. Requirement: globus-cli installed and an endpoint created. Specify your unique user identifier (UUID) as the input parameter.
+Use Globus if Aspera is not specified or Aspera transfer fails. Requirement: globus-cli installed and an endpoint
+created. Specify your unique user identifier (UUID) as the input parameter.
 
 ``-f, --globus-force-login``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Force login to Globus. Login even if the globus-cli already has valid login credentials. Any existing credentials will be removed from local storage and globally revoked.
+Force login to Globus. Login even if the globus-cli already has valid login credentials. Any existing credentials will
+be removed from local storage and globally revoked.
 
 ``-e ENTRY_THUMBNAIL, --entry-thumbnail ENTRY_THUMBNAIL``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Thumbnail image that will represent your deposition on EMPIAR pages. Minimum size is 400 x 400, preferred format is png. If none is provided, then the image from the related EMDB entry will be used.
+Thumbnail image that will represent your deposition on EMPIAR pages. Minimum size is 400 x 400, preferred format is png.
+If none is provided, then the image from the related EMDB entry will be used.
 
 ``-r ENTRY_ID ENTRY_DIR, --resume ENTRY_ID ENTRY_DIR``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Resume Aspera upload or re-deposit an entry. The entry has to be successfully created as specifying EMPIAR entry ID and entry directory is required. All entry metadata will be replaced with the one provided in the JSON file. Aspera transfer will continue from where it stopped.
+Resume Aspera upload or re-deposit an entry. The entry has to be successfully created as specifying EMPIAR entry ID and
+entry directory is required. All entry metadata will be replaced with the one provided in the JSON file. Aspera transfer will continue from where it stopped.
+
+``-gu USERNAME_RIGHTS, --grant-rights-usernames USERNAME_RIGHTS``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``-ge EMAIL_RIGHTS, --grant-rights-emails EMAIL_RIGHTS``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``-gu ORCID_RIGHTS, --grant-rights-usernames ORCID_RIGHTS``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Grant rights based on usernames, emails or ORCiDs. ``USERNAME_RIGHTS``, ``EMAIL_RIGHTS`` and ``ORCID_RIGHTS`` are
+comma separated lists of usernames, emails, ORCiDs and rights in format `username:rights`, `email:rights` and
+`orcid:rights`. Rights can be 1 - Owner, 2 - View only, 3 - View and Edit, 4 - View, Edit and Submit. There can be
+only one deposition owner.
 
 ``-i, --ignore-certificate``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -113,6 +139,14 @@ Examples:
 
   empiar-depositor -a ~/Applications/Aspera\ Connect.app/Contents/Resources/ascp 0123456789 ~/Documents/empiar_deposition_1.json ~/Downloads/micrographs
 
+.. code:: bash
+
+  empiar-depositor -a ~/Applications/Aspera\ Connect.app/Contents/Resources/ascp 0123456789 ~/Documents/empiar_deposition_1.json ~/Downloads/micrographs -gu johndoe:1,jamessmith:3
+
+.. code:: bash
+
+  empiar-depositor -a ~/Applications/Aspera\ Connect.app/Contents/Resources/ascp 0123456789 ~/Documents/empiar_deposition_1.json ~/Downloads/micrographs -gu johndoe:4,jamessmith:1 -ge jeremycarpenter@email.com:3 -go 0000-0000-0000-0001:2,0000-0000-1000-0002:4
+
 .. code:: bash
 
   empiar-depositor -r 10 ABC123 -e ~/Downloads/dep_thumb.png 0123456789 -g 01234567-89a-bcde-fghi-jklmnopqrstu ~/Documents/empiar_deposition_1.json ~/Downloads/micrographs

diff --git a/empiar_depositor/empiar_depositor.py b/empiar_depositor/empiar_depositor.py
@@ -19,7 +19,8 @@
 under the License.
 
 Version history
-1.6b21, 20200429, Andrii Iudin: Added support of rights granting and of EER, PNG and JPEG image set formats and 4 BIT
+1.6b22, 20201217, Andrii Iudin: Updated documentation
+1.6b21, 20201216, Andrii Iudin: Added support of rights granting and of EER, PNG and JPEG image set formats and 4 BIT
 INTEGER voxel type
 1.6b20, 20200429, Andrii Iudin: Schema update - now we accept references to IDR.
 1.6b19, 20200302, Andrii Iudin: It is now possible to upload Big Data Viewer HDF5 files.
@@ -181,6 +182,13 @@ def globus_upload_wait(task_id):
 
     @staticmethod
     def prepare_rights_data(data):
+        """
+        Turn the comma separated list of user-specific fields and rights into a dictionary
+        :param data: a string that contains a comma separated list of colon separated user-specific fields and rights,
+        for example, 'usernam1:2,username2:1'
+        :return: a dictionary with user-specific fields as keys and corresponding rights as values, for example,
+        {'username1': 2, 'username2': 1}
+        """
         if data:
             if data.count(':') == data.count(',') + 1:
                 data_ready = {k[0]: k[1] for k in tuple(i.split(':') for i in data.split(','))}
@@ -527,7 +535,7 @@ def main(args=None):
     empiar-depositor -r 10 ABC123 -e ~/Downloads/dep_thumb.png 0123456789 -g 01234567-89a-bcde-fghi-jklmnopqrstu ~/Docu\
 ments/empiar_deposition_1.json ~/Downloads/micrographs
                 """
-        version = "1.6b21"
+        version = "1.6b22"
 
         possible_rights_help_text = "Rights can be 1 - Owner, 2 - View only, 3 - View and Edit, 4 - View, Edit and " \
                                     "Submit. There can be only one deposition owner."
@@ -563,14 +571,14 @@ def main(args=None):
                                  "related EMDB entry will be used.")
 
         parser.add_argument("-gu", "--grant-rights-usernames", action="store",
-                            help="Comma separated list of usernames and rights in format <username>:<rights>. " +
-                                 possible_rights_help_text)
+                            help="Grant rights. Provide a comma separated list of usernames and rights in format "
+                                 "<username>:<rights>. " + possible_rights_help_text)
         parser.add_argument("-ge", "--grant-rights-emails", action="store",
-                            help="Comma separated list of emails addresses and rights in format "
-                                 "<email_address>:<rights>. " + possible_rights_help_text)
+                            help="Grant rights. Provide a comma separated list of emails addresses and rights in "
+                                 "format <email_address>:<rights>. " + possible_rights_help_text)
         parser.add_argument("-go", "--grant-rights-orcids", action="store",
-                            help="Comma separated list of ORCiDs and rights in format <orcid>:<rights>. " +
-                                 possible_rights_help_text)
+                            help="Grant rights. Provide a comma separated list of ORCiDs and rights in format "
+                                 "<orcid>:<rights>. " + possible_rights_help_text)
 
         parser.add_argument("-r", "--resume", action="store", metavar=("ENTRY_ID", "ENTRY_DIR"),
                             help="Resume Aspera upload. The entry has to be successfully created beforehand as "

diff --git a/empiar_depositor/tests/testutils.py b/empiar_depositor/tests/testutils.py
@@ -13,13 +13,23 @@
 
 
 class EmpiarDepositorTest(unittest.TestCase):
+    """
+    Test class for EMPIAR depositions
+    """
     current_dir = os.path.dirname(os.path.abspath(__file__))
     json_path = os.path.join(current_dir, "deposition_json/working_example.json")
     thumbnail_path = os.path.join(current_dir, "img/entry_thumbnail.gif")
 
 
 @contextmanager
 def capture(command, *args, **kwargs):
+    """
+    Capture command to assess its output
+    :param command: the command to be captured
+    :param args: arguments for the command
+    :param kwargs: keyword arguments for the command
+    :return: the output of the command
+    """
     out, sys.stdout = sys.stdout, StringIO()
     try:
         command(*args, **kwargs)
@@ -28,7 +38,16 @@ def capture(command, *args, **kwargs):
     finally:
         sys.stdout = out
 
+
 def mock_response(mocked_response=None, status_code=None, headers=None, json=None):
+    """
+    Mock a response by assigning attributes and methods return values
+    :param mocked_response: response that is to be mocked
+    :param status_code: mock status code of the response
+    :param headers: mock headers of the response
+    :param json: mock returned JSON from the response
+    :return: Mocked response enhanced with provided attributes and methods return values
+    """
     mocked_response.return_value = Mock(ok=True, spec=Response)
 
     if status_code:

diff --git a/setup.py b/setup.py
@@ -11,7 +11,7 @@
 
 setup(
     name='empiar-depositor',
-    version='1.6b21',
+    version='1.6b22',
     packages=find_packages(),
     author="Andrii Iudin",
     author_email="andrii@ebi.ac.uk, andrii.iudin@gmail.com",