From 77314a170362ead463e2a3bc7a8e2506d478b4b1 Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Sun, 22 Dec 2024 20:27:47 -0500 Subject: [PATCH 1/5] fix typo and add examples --- doc/source/examples/tools_example.rst | 27 +++++++++++++++++++++++--- doc/source/utilities/tools_utility.rst | 9 +++++++-- 2 files changed, 31 insertions(+), 5 deletions(-) diff --git a/doc/source/examples/tools_example.rst b/doc/source/examples/tools_example.rst index 60746e6f..51cb4470 100644 --- a/doc/source/examples/tools_example.rst +++ b/doc/source/examples/tools_example.rst @@ -41,7 +41,7 @@ The function will return .. code-block:: python - {"owner_email": "janedoe@email.com", "owner_name": "Jane Doe", "owner_orcid": "0000-0000-0000-0000"} + {"owner_name": "Jane Doe", "owner_email": "janedoe@email.com", "owner_orcid": "0000-0000-0000-0000"} Where does ``get_user_info()`` get the user information from? @@ -77,6 +77,7 @@ When building an application where you want to capture data-owner information, w ``check_and_build_global_config()`` first followed by ``get_user_info`` in your app workflow. E.g., .. code-block:: python + from diffpy.utils.tools import check_and_build_global_config, get_user_info from datetime import datetime import json @@ -95,12 +96,32 @@ 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. +What happens when you run ``check_and_build_global_config()``? +-------------------------------------------------------------- + +When you set ``skip_config_creation`` to ``False`` and there is no existing global configuration file, +the function will prompt you for inputs (name, email, ORCID). +An example of the prompts you may see is: + +.. code-block:: python + + Please enter the name you would want future work to be credited to: Jane Doe + Please enter your email: janedoe@example.com + Please enter your orcid ID if you know it: 0000-0000-0000-0000 + + +After receiving the inputs, the function will write the following to the file: + +.. code-block:: python + {"owner_name": "Jane Doe", "owner_email": "janedoe@email.com", "owner_orcid": "0000-0000-0000-0000"} + + 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 +workflow. You can also simply edit the ``diffpyconfig.json`` file directly using a text editor. Locate the file ``diffpyconfig.json``, in your home directory and open it in an editor :: @@ -111,7 +132,7 @@ Locate the file ``diffpyconfig.json``, in your home directory and open it in an "owner_orcid": "0000-0000-4321-1234" } - Then you can edit the username and email as needed, make sure to save your edits. +Then you can edit the username and email as needed, make sure to save your edits. Automatically Capture Info about a Software Package Being Used ============================================================== diff --git a/doc/source/utilities/tools_utility.rst b/doc/source/utilities/tools_utility.rst index 01685a93..e0562faf 100644 --- a/doc/source/utilities/tools_utility.rst +++ b/doc/source/utilities/tools_utility.rst @@ -5,12 +5,17 @@ Tools Utility The ``diffpy.utils.tools`` module provides tool functions for use with diffpy apps. -- ``get_user_info()``: This function is designed for managing and tracking username and email information. - +- ``get_user_info()``: This function is designed for managing and tracking user information (name, email, orcid). Developers can use this function to simplify the process of loading, merging, and saving information consistently and easily. Additionally, it saves the effort of re-entering information, and allows overriding current information by passing parameters. +- ``check_and_build_global_config()``: This function helps create a global configuration file + that can be used by ``get_user_info()``. + If no existing configuration file is found, and the user allows inputs, this function prompts for information. + The provided inputs are then saved to a global configuration file. + This file can be reused later by ``get_user_info()`` to ensure that the work credits and user information are consistently stored. + - ``get_package_info()``: This function loads package name and version information into a dictionary. It updates the package information under the key "package_info" in the format {"package_name": "version_number"}, resulting in an entry in the passed metadata dictionary that looks like From ddf7180afdde32c7bbc9993a38eecb582ad14858 Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Sun, 22 Dec 2024 20:28:24 -0500 Subject: [PATCH 2/5] fix typos --- src/diffpy/utils/tools.py | 41 ++++++--------------------------------- 1 file changed, 6 insertions(+), 35 deletions(-) diff --git a/src/diffpy/utils/tools.py b/src/diffpy/utils/tools.py index 91505e6f..87d69a64 100644 --- a/src/diffpy/utils/tools.py +++ b/src/diffpy/utils/tools.py @@ -4,29 +4,7 @@ from pathlib import Path -def clean_dict(obj): - """ - Remove keys from the dictionary where the corresponding value is None. - - Parameters - ---------- - obj: dict - The dictionary to clean. If None, initialize as an empty dictionary. - - Returns - ------- - dict: - The cleaned dictionary with keys removed where the value is None. - - """ - obj = obj if obj is not None else {} - for key, value in copy(obj).items(): - if not value: - del obj[key] - return obj - - -def stringify(obj): +def _stringify(obj): """ Convert None to an empty string. @@ -43,7 +21,7 @@ def stringify(obj): return obj if obj is not None else "" -def load_config(file_path): +def _load_config(file_path): """ Load configuration from a .json file. @@ -67,13 +45,6 @@ def load_config(file_path): return {} -def _sorted_merge(*dicts): - merged = {} - for d in dicts: - merged.update(d) - return merged - - def _create_global_config(args): username = input( f"Please enter the name you would want future work to be credited to " f"[{args.get('username', '')}]: " @@ -81,7 +52,7 @@ def _create_global_config(args): email = input(f"Please enter the your email " f"[{args.get('email', '')}]: ").strip() or args.get("email", "") return_bool = False if username is None or email is None else True with open(Path().home() / "diffpyconfig.json", "w") as f: - f.write(json.dumps({"username": stringify(username), "email": stringify(email)})) + f.write(json.dumps({"username": _stringify(username), "email": _stringify(email)})) print( f"You can manually edit the config file at {Path().home() / 'diffpyconfig.json'} using any text editor.\n" f"Or you can update the config file by passing new values to get_user_info(), " @@ -116,7 +87,7 @@ def get_user_info(owner_name=None, owner_email=None, owner_orcid=None): 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. + owner_orcid: string, optional, default is the value stored in the global or local config file. The ORCID id of the user/owner Returns @@ -130,8 +101,8 @@ def get_user_info(owner_name=None, owner_email=None, owner_orcid=None): for key, value in copy(runtime_info).items(): if value is None or value == "": del runtime_info[key] - global_config = load_config(Path().home() / "diffpyconfig.json") - local_config = load_config(Path().cwd() / "diffpyconfig.json") + global_config = _load_config(Path().home() / "diffpyconfig.json") + local_config = _load_config(Path().cwd() / "diffpyconfig.json") # if global_config is None and local_config is None: # print( # "No global configuration file was found containing " From c29053dacc307a9e3fbca8bf59679aed8ee45d1a Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Mon, 23 Dec 2024 10:21:50 -0500 Subject: [PATCH 3/5] remove unnecessary function --- src/diffpy/utils/tools.py | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/src/diffpy/utils/tools.py b/src/diffpy/utils/tools.py index 87d69a64..a6c30ed3 100644 --- a/src/diffpy/utils/tools.py +++ b/src/diffpy/utils/tools.py @@ -45,22 +45,6 @@ def _load_config(file_path): return {} -def _create_global_config(args): - username = input( - f"Please enter the name you would want future work to be credited to " f"[{args.get('username', '')}]: " - ).strip() or args.get("username", "") - email = input(f"Please enter the your email " f"[{args.get('email', '')}]: ").strip() or args.get("email", "") - return_bool = False if username is None or email is None else True - with open(Path().home() / "diffpyconfig.json", "w") as f: - f.write(json.dumps({"username": _stringify(username), "email": _stringify(email)})) - print( - f"You can manually edit the config file at {Path().home() / 'diffpyconfig.json'} using any text editor.\n" - f"Or you can update the config file by passing new values to get_user_info(), " - f"see examples here: https://www.diffpy.org/diffpy.utils/examples/toolsexample.html" - ) - return return_bool - - def get_user_info(owner_name=None, owner_email=None, owner_orcid=None): """ Get name, email and orcid of the owner/user from various sources and return it as a metadata dictionary From cc8cf059cc9dee12c9c1eb8501d4b621bb088257 Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Mon, 23 Dec 2024 10:23:45 -0500 Subject: [PATCH 4/5] no news added --- news/user_info_doc.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 news/user_info_doc.rst diff --git a/news/user_info_doc.rst b/news/user_info_doc.rst new file mode 100644 index 00000000..43bee6bd --- /dev/null +++ b/news/user_info_doc.rst @@ -0,0 +1,23 @@ +**Added:** + +* no news added: simply adding documentation for config update workflow + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* From 13742d0ada437cd21e207e1df96048feb97a7945 Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Mon, 23 Dec 2024 15:11:52 -0500 Subject: [PATCH 5/5] edit docs --- doc/source/examples/tools_example.rst | 6 ++---- doc/source/utilities/tools_utility.rst | 4 ++-- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/doc/source/examples/tools_example.rst b/doc/source/examples/tools_example.rst index 51cb4470..268c26dd 100644 --- a/doc/source/examples/tools_example.rst +++ b/doc/source/examples/tools_example.rst @@ -110,10 +110,8 @@ An example of the prompts you may see is: Please enter your orcid ID if you know it: 0000-0000-0000-0000 -After receiving the inputs, the function will write the following to the file: - -.. code-block:: python - {"owner_name": "Jane Doe", "owner_email": "janedoe@email.com", "owner_orcid": "0000-0000-0000-0000"} +After receiving the inputs, the function will write the information to +the `diffpyconfig.json` file in your home directory. I entered the wrong information in my config file so it always loads incorrect information, how do I fix that? diff --git a/doc/source/utilities/tools_utility.rst b/doc/source/utilities/tools_utility.rst index e0562faf..e524a65b 100644 --- a/doc/source/utilities/tools_utility.rst +++ b/doc/source/utilities/tools_utility.rst @@ -11,8 +11,8 @@ The ``diffpy.utils.tools`` module provides tool functions for use with diffpy ap passing parameters. - ``check_and_build_global_config()``: This function helps create a global configuration file - that can be used by ``get_user_info()``. - If no existing configuration file is found, and the user allows inputs, this function prompts for information. + that can be used by, for example, ``get_user_info()``. + If no existing configuration file is found, this function prompts for information. The provided inputs are then saved to a global configuration file. This file can be reused later by ``get_user_info()`` to ensure that the work credits and user information are consistently stored.