Update utils.py

[Jk40git]

Change the _find's docstring to _load_json's

Contributor checklist

• [] This pull request is on a separate branch and not the main branch

---

Description

Related issue

• #ISSUE_NUMBER

[github-actions]

Thank you for the pull request!

The Scribe team will do our best to address your contribution as soon as we can. The following is a checklist for maintainers to make sure this process goes as well as possible. Feel free to address the points below yourself in further commits if you realize that actions are needed :)

If you're not already a member of our public Matrix community, please consider joining! We'd suggest using Element as your Matrix client, and definitely join the General and Data rooms once you're in. It'd be great to have you!

Maintainer checklist

• The commit messages for the remote branch should be checked to make sure the contributor's email is set up correctly so that they receive credit for their contribution

  • The contributor's name and icon in remote commits should be the same as what appears in the PR
  • If there's a mismatch, the contributor needs to make sure that the email they use for GitHub matches what they have for git config user.email in their local Scribe-Data repo

• The CHANGELOG has been updated with a description of the changes for the upcoming release and the corresponding issue (if necessary)

[andrewtavis]

I see there was some confusion here, @Jk40git. Big thing is that we don't want the docstring to "be the docstring of the other one", but we want them to have the same style. For find we currently have:

    """
    Each 'language', (english, german,..., etc) is a dictionary of key/value pairs:

        entry = {
            "language": "english",
            "iso": "en",
            "qid": "Q1860",
            "remove-words": [...],
            "ignore-words": [...]
        }

    Given a key/value pair, the 'source', and the 'target' key, get the 'target' value.

    Args:
        source_value (str): e.g. 'english'.
        source_key (str): e.g. 'language'.
        target_key (str): e.g. 'iso'.
        error_msg (str): for when a value cannot be found.

    Raises:
        ValueError: when a source_value is not supported.

    Returns:
        The 'target' value given the passed arguments.
    """

What this should be is:

    """
    Each 'language', (english, german,..., etc) is a dictionary of key/value pairs:

        entry = {
            "language": "english",
            "iso": "en",
            "qid": "Q1860",
            "remove-words": [...],
            "ignore-words": [...]
        }

    Given a key/value pair, the 'source', and the 'target' key, get the 'target' value.

    Parameters
    ----------
        source_value : str
            The source value to find equivalents for (e.g. 'english').
        source_key : str
            The source key to reference (e.g. 'language').
        target_key : str
            The key to target (e.g. 'iso').
        error_msg : str
            The message displayed when a value cannot be found.

    Raises
    ------
        ValueError : when a source_value is not supported.

    Returns
    -------
        The 'target' value given the passed arguments.
    """

The big thing is that everywhere that we have Args: in a docstring we want:

Parameters
----------
    {LIST_OF_THE_ARGS}

And everywhere we have Returns: we want:

Returns
-------
    {LIST_OF_RETURN_VALUES}

Can you convert the docstring of _find over to what I have above, and then I can send along a list of functions that we also need to do other conversions for?

[Jk40git]

@andrewtavis Just made an edit #63

[andrewtavis]

Nice, yes, this is looking good @Jk40git! Here are the other docstrings that need edits:

• In checkquery.py basically all for function docstrings need to be edited
• In utils.py we need _find as you already did and then check_command_line_args and check_and_return_command_line_args

Want to send along another commit with all of these changes, and then we can close this up? In cases where there's a section that's not Args: or Returns:, let's just keep it in order and put dashes under it. So for example Raises: we can also do:

Raises
------

as in the example above :) Let me know if there are any questions on this!

[Jk40git]

Nice, yes, this is looking good @Jk40git! Here are the other docstrings that need edits:

• In checkquery.py basically all for function docstrings need to be edited
• In utils.py we need _find as you already did and then check_command_line_args and check_and_return_command_line_args

Want to send along another commit with all of these changes, and then we can close this up? In cases where there's a section that's not Args: or Returns:, let's just keep it in order and put dashes under it. So for example Raises: we can also do:

Raises
------

as in the example above :) Let me know if there are any questions on this!

Do you want me to change the check_command_line_args and check_and_return_command_line_args with the same docstring from _find?

[andrewtavis]

Minor changes sent along in the most recent commit finishes this up, @Jk40git. Thanks! Will move to the others now :)

[andrewtavis]

Don't worry about the Mac builds, by the way. This is known in #61 :)