Author terry.reedy
Recipients ced, docs@python, ezio.melotti, georg.brandl, mark.dickinson, skrah, terry.reedy
Date 2013-03-15.20:21:06
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1363378867.07.0.810263305354.issue13918@psf.upfronthosting.co.za>
In-reply-to
Content
I find the idea of intentionally not documenting a public parameter and the full signature of a function somewhat strange, especially when it is already automatically partially-documented.

>>> import locale
>>> help(locale.atof)
Help on function atof in module locale:

atof(string, func=<class 'float'>)
    Parses a string as a float according to the locale settings.
# 2.7, 3.2, 3.3

Not documenting the full signature of a function seems to me contrary to proper policy. That aside, the func parameter is, to me, a useful feature, not just an implementation detail

The way to have factored out the common normalization without a func parameter is obvious: define a private normalization function.

def _anormalize(string):
    "remove thousands separators, make decimal dot"
    ts = localeconv()['thousands_sep']
    if ts:
        string = string.replace(ts, '')
    #next, replace the decimal point with a dot
    dd = localeconv()['decimal_point']
    if dd:
        string = string.replace(dd, '.')
    return string

def atof(string):
    "Parses a string as a float according to the locale settings."
    return float(_anormalize(string))

def atoi(string):  # changed from str
    "Converts a string to an integer according to the locale settings."
    return int(_anormalize(string))

But Martin von Loewis, the original author did not do this. I would not assume that he "thought that copying 3 lines from atof into atoi was a bad idea." without asking him.  Whatever his conscious intention, the func parameter *does* have the advantage of allowing alternate float string to number converters.  We now have another one in the stdlib besides decimal.Decimal: fractions.Fractions.

>>> locale.atof('99,999.99', F)
Fraction(9999999, 100)
# versus
>>> F(locale.atof('99,999.99'))
Fraction(6871946986405233, 68719476736)

There are also 3rd party float implementations, such as indefinite precision binary floats. Does anyone still object to properly documenting this useful feature? I am willing to do the commits.

As to the patch and atof docstring, I thinks 'converts' (used in atoi docstring) is better than 'parses'.  So I would change both.
History
Date User Action Args
2013-03-15 20:21:07terry.reedysetrecipients: + terry.reedy, georg.brandl, mark.dickinson, ezio.melotti, ced, skrah, docs@python
2013-03-15 20:21:07terry.reedysetmessageid: <1363378867.07.0.810263305354.issue13918@psf.upfronthosting.co.za>
2013-03-15 20:21:07terry.reedylinkissue13918 messages
2013-03-15 20:21:06terry.reedycreate