Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add docs for check_and_build_global_config() #270

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 22 additions & 3 deletions doc/source/examples/tools_example.rst
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ The function will return

.. code-block:: python

{"owner_email": "[email protected]", "owner_name": "Jane Doe", "owner_orcid": "0000-0000-0000-0000"}
{"owner_name": "Jane Doe", "owner_email": "[email protected]", "owner_orcid": "0000-0000-0000-0000"}


Where does ``get_user_info()`` get the user information from?
Expand Down Expand Up @@ -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
Expand All @@ -95,12 +96,30 @@ 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()``?
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add example

--------------------------------------------------------------

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: [email protected]
Please enter your orcid ID if you know it: 0000-0000-0000-0000


After receiving the inputs, the function will write the information to
the `diffpyconfig.json` file in your home directory.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I deleted the example here - there are examples both before and after this section



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 ::
Expand All @@ -111,7 +130,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.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reformat


Automatically Capture Info about a Software Package Being Used
==============================================================
Expand Down
9 changes: 7 additions & 2 deletions doc/source/utilities/tools_utility.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
yucongalicechen marked this conversation as resolved.
Show resolved Hide resolved
that can be used by, for example, ``get_user_info()``.
If no existing configuration file is found, this function prompts for information.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

deleted "allows inputs"

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
Expand Down
23 changes: 23 additions & 0 deletions news/user_info_doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
**Added:**

* no news added: simply adding documentation for config update workflow

**Changed:**

* <news item>

**Deprecated:**

* <news item>

**Removed:**

* <news item>

**Fixed:**

* <news item>

**Security:**

* <news item>
55 changes: 5 additions & 50 deletions src/diffpy/utils/tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

make this function private and remove unncessary functions

"""
Convert None to an empty string.

Expand All @@ -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.

Expand All @@ -67,29 +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', '')}]: "
).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
Expand All @@ -116,7 +71,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
Expand All @@ -130,8 +85,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 "
Expand Down
Loading