docs

Author: sbillinge

doc/source/examples/tools_example.rst

@@ -13,11 +13,11 @@ Automatically Capture User Info
 One task we would like to do is to capture and propagate useful metadata that describes the diffraction data.
 Some is essential such as wavelength and radiation type. Other metadata is useful such as information about the
 sample, co-workers and so on.  However, one of the most important bits of information is the name of the data owner.
-For example, in ``DiffractionObjects`` this is stored in the ``metadata`` dictionary as ``username``, ``user_email``,
-and ``user_orcid``.
+For example, in ``DiffractionObjects`` this is stored in the ``metadata`` dictionary as ``owner_name``, ``owner_email``,
+and ``owner_orcid``.
 
 To reduce experimenter overhead when collecting this information, we have developed an infrastructure that helps
-to capture this information automatically when you are using `DiffractionObjects` and other diffpy tools.
+to capture this information automatically when you are using ``DiffractionObjects`` and other diffpy tools.
 You may also reuse this infrastructure for your own projects using tools in this tutorial.
 
 This example will demonstrate how ``diffpy.utils`` allows us to conveniently load and manage user and package information.
@@ -28,8 +28,9 @@ Load user info into your program
 
 To use this functionality in your own code make use of the ``get_user_info`` function in
 ``diffpy.utils.tools`` which will search for information about the user, parse it, and return
-it in a dictionary object e.g. if the user is "Jane Doe" with email "janedoe@gmail.com" and the
-function can find the information, if you type this
+it in a dictionary object e.g. if the user is "Jane Doe" with email "janedoe@gmail.com" and ORCID
+"0000-0000-0000-0000", and if the
+function can find the information (more on this below), if you type this
 
 .. code-block:: python
 
@@ -40,16 +41,17 @@ The function will return
 
 .. code-block:: python
 
-        {"email": "janedoe@email.com", "username": "Jane Doe"}
+        {"owner_email": "janedoe@email.com", "owner_name": "Jane Doe", "owner_orcid": "0000-0000-0000-0000"}
 
 
 Where does ``get_user_info()`` get the user information from?
 -------------------------------------------------------------
 
 The function will first attempt to load the information from configuration files with the name ``diffpyconfig.json``
 on your hard-drive.
-It looks first for the file in the current working directory.  If it cannot find it there it will look
-user's home, i.e., login, directory.  To find this directory, open a terminal and a unix or mac system type ::
+It looks for files in the current working directory and in the computer-user's home (i.e., login) directory.
+For example, it might be in C:/Users/yourname`` or something like that, but to find this directory, open
+a terminal and a unix or mac system type ::
 
     cd ~
     pwd
@@ -58,67 +60,55 @@ Or type ``Echo $HOME``.  On a Windows computer ::
 
     echo %USERPROFILE%"
 
+It is also possible to override the values in the config files at run-time by passing values directly into the
+function according to ``get_user_info``, for example,
+``get_user_info(owner_name="Janet Doe", owner_email="janetdoe@email.com", owner_orcid="1111-1111-1111-1111")``.
+The information to pass into ``get_user_info`` could be entered by a user through a command-line interface
+or into a gui.
+
 What if no config files exist yet?
 -----------------------------------
 
-If no configuration files can be found, the function attempts to create one in the user's home
-directory.  The function will pause execution and ask for a user-response to enter the information.
-It will then write the config file in the user's home directory.
-
-In this way, the next, and subsequent times the program is run, it will no longer have to prompt the user
-as it will successfully find the new config file.
-
-Getting user data with no config files and with no interruption of execution
-----------------------------------------------------------------------------
+If no configuration files can be found, they can be created using a text editor, or by using a diffpy tool
+called ``check_and_build_global_config()`` which, if no global config file can be found, prompts the user for the
+information then writes the config file in the user's home directory.
 
-If you would like get run ``get_user_data()`` but without execution interruption even if it cannot find
-an input file, type
+When building an application where you want to capture data-owner information, we recommend you execute
+``check_and_build_global_config()`` first followed by ``get_user_info`` in your app workflow.  E.g.,
 
 .. code-block:: python
-
-    user_data = get_user_data(skip_config_creation=True)
-
-Passing user information directly to ``get_user_data()``
---------------------------------------------------------
-
-It can be passed user information which fully or partially overrides looking in config files
-For example, in this way it would be possible to pass in information
-that is entered through a gui or command line interface. E.g.,
-
-    .. code-block:: python
-
-        new_user_info = get_user_info({"username": "new_username", "email": "new@example.com"})
-
-This returns ``{"username": "new_username", "email": "new@example.com"}`` (and so, effectively, does nothing)
-However, You can update only the username or email individually, for example
-
-.. code-block:: python
-
-        new_user_info = get_user_info({"username": new_username})
-
-will return ``{"username": "new_username", "email": "janedoe@gmail.com"}``
-if it found ``janedoe@gmail.com`` as the email in the config file.
-Similarly, you can update only the email in the returned dictionary,
-
-.. code-block:: python
-
-        new_user_info = get_user_info({"email": new@email.com})
-
-which will return ``{"username": "Jane Doe", "email": "new@email.com"}``
-if it found ``Jane Doe`` as the user in the config file.
-
-I entered the wrong information in my config file so it always loads incorrect information
-------------------------------------------------------------------------------------------
-
-You can use of the above methods to temporarily override the incorrect information in your
-global config file. However, it is easy to fix this simply by editing that file using a text
+    from diffpy.utils.tools import check_and_build_global_config, get_user_info
+    from datetime import datetime
+    import json
+
+    def my_cool_data_enhancer_app_main(data, filepath):
+        check_and_build_global_config()
+        metadata_enhanced_data = get_user_info()
+        metadata_enhanced_data.update({"creation_time": datetime.now(),
+                                       "data": data})
+        with open(filepath, "w") as f:
+            json.dump(metadata_enhanced_data, f)
+
+``check_and_build_global_config()`` only
+interrupts execution if it can't find a valid config file, and so if the user enters valid information
+it will only run once.  However, if you want to bypass this behavior,
+``check_and_build_global_config()`` takes an optional boolean ``skip_config_creation`` parameter that
+could be set to ``True`` at runtime to override the config creation.
+
+I entered the wrong information in my config file so it always loads incorrect information, how do I fix that?
+--------------------------------------------------------------------------------------------------------------
+
+It is easy to fix this simply by deleting the global and/or local config files, which will allow
+you to re-enter the information during the ``check_and_build_global_config()`` initialization
+workflow.   You can also simply editi the ``diffpyconfig.json`` file directly using a text
 editor.
 
 Locate the file ``diffpyconfig.json``, in your home directory and open it in an editor ::
 
     {
-        "username": "John Doe",
-        "email": "john.doe@example.com"
+        "owner_name": "John Doe",
+        "owner_email": "john.doe@example.com"
+        "owner_orcid": "0000-0000-4321-1234"
     }
 
    Then you can edit the username and email as needed, make sure to save your edits.

src/diffpy/utils/tools.py

@@ -92,22 +92,38 @@ def _create_global_config(args):
 
 def get_user_info(owner_name=None, owner_email=None, owner_orcid=None):
     """
-    Get username, email and orcid configuration.
-
-    First attempts to load config file from global and local paths.
-    If neither exists, creates a global config file.
-    It prioritizes values from args, then local, then global.
-    Removes invalid global config file if creation is needed, replacing it with empty username and email.
+    Get name, email and orcid of the owner/user from various sources and return it as a metadata dictionary
+
+    The function looks for the information in json format configuration files with the name 'diffpyconfig.json'.
+    These can be in the user's home directory and in the current working directory.  The information in the
+    config files are combined, with the local config overriding the home-directory one.  Values for
+    owner_name, owner_email, and owner_orcid may be passed in to the function and these override the values
+    in the config files.
+
+    A template for the config file is below.  Create a text file called 'diffpyconfig.json' in your home directory
+    and copy-paste the template into it, editing it with your real information.
+    {
+      "owner_name": "<your name as you would like it stored with your data>>",
+      "owner_email": "<your_associated_email>>@email.com",
+      "owner_orcid": "<your_associated_orcid if you would like this stored with your data>>"
+    }
+    You may also store any other gloabl-level information that you would like associated with your
+    diffraction data in this file
 
     Parameters
     ----------
-    args argparse.Namespace
-        The arguments from the parser, default is None.
+    owner_name: string, optional, default is the value stored in the global or local config file.
+        The name of the user who will show as owner in the metadata that is stored with the data
+    owner_email: string, optional, default is the value stored in the global or local config file.
+        The email of the user/owner
+    owner_name:  string, optional, default is the value stored in the global or local config file.
+        The ORCID id of the user/owner
 
     Returns
     -------
-    dict or None:
-        The dictionary containing username and email with corresponding values.
+    dict:
+        The dictionary containing username, email and orcid of the user/owner, and any other information
+        stored in the global or local config files.
 
     """
     runtime_info = {"owner_name": owner_name, "owner_email": owner_email, "owner_orcid": owner_orcid}