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

nice_number docstring suggests global default for denominators which is not present #189

Open
ChanceNCounter opened this issue Apr 12, 2021 · 0 comments
Labels
Projects

Comments

@ChanceNCounter
Copy link
Contributor

Excerpt from the definition and docstring:

def nice_number(number, lang='', speech=True, denominators=None):
    """Format a float to human readable functions

    This function formats a float to human understandable functions. Like
    4.5 becomes 4 and a half for speech and 4 1/2 for text
    Args:
        number (int or float): the float to format
        lang (str): code for the language to use
        speech (bool): format for speech (True) or display (False)
        denominators (iter of ints): denominators to use, default [1 .. 20]

As you can see, the "top level" function, which can be called by the localizer's run_own_code_on parameter, suggests a default range of 1-20, but has no such default, nor does its logic enforce that value. Although the English-language function (and presumably others, haven't checked) defaults to range(1, 21), this value could hypothetically be different for a particular language.

Maintainers may recall that "top level" functions' default parameters are ignored by the localizer when successfully calling a localized function, so the only way to provide accurate defaults in these docstrings is to ensure that defaults are uniform across localizations. However, if a function has the run_own_code_on parameter, its actual contents can be executed.

Furthermore, we've done a reasonable job of keeping the top-level signatures' default values consistent with their expected behavior in localized versions, so that users reading them via autocomplete have an idea what to expect.

Either the docstring should change to reflect the function's default value, or the function's default value should be changed to reflect the localized functions' defaults.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
Roadmap
v0.4.3
Development

No branches or pull requests

1 participant