locale.atof documentation is missing func argument

[cedk]

BPO	13918
Nosy	@birkenfeld, @terryjreedy, @mdickinson, @pitrou, @vstinner, @ezio-melotti, @cedk
Files	doc_atof.patch delocalize.patch delocalize.patch delocalize.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2014-10-23.20:53:30.100>
created_at = <Date 2012-02-01.14:12:20.474>
labels = ['type-feature', 'library']
title = 'locale.atof documentation is missing func argument'
updated_at = <Date 2014-10-23.21:04:24.618>
user = 'https://github.com/cedk'

bugs.python.org fields:

activity = <Date 2014-10-23.21:04:24.618>
actor = 'georg.brandl'
assignee = 'none'
closed = True
closed_date = <Date 2014-10-23.20:53:30.100>
closer = 'pitrou'
components = ['Library (Lib)']
creation = <Date 2012-02-01.14:12:20.474>
creator = 'ced'
dependencies = []
files = ['29414', '36955', '36960', '36964']
hgrepos = []
issue_num = 13918
keywords = ['patch']
message_count = 24.0
messages = ['152430', '152478', '152479', '184119', '184121', '184165', '184167', '184168', '184226', '184251', '184292', '184295', '184612', '229570', '229573', '229641', '229644', '229660', '229899', '229901', '229902', '229903', '229905', '229906']
nosy_count = 9.0
nosy_names = ['georg.brandl', 'terry.reedy', 'mark.dickinson', 'pitrou', 'vstinner', 'ezio.melotti', 'ced', 'docs@python', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue13918'
versions = ['Python 3.5']

[cedk]

atof has a func argument used to instantiate the result but it is missing in the documentation.

[birkenfeld]

I don't think that argument needs to be documented. It's just there because somebody thought that copying 3 lines from atof into atoi was a bad idea.

[cedk]

Indeed I find it useful to use to get a Decimal instead of a float.
So I was wondering if I can rely on it or not in my application?

[ezio-melotti]

It looks like an implementation detail to me, so I tend to agree with Georg. I'm not sure if this should be noted in the code though.

[cedk]

Then I think we miss a locale.atod to parse string to Decimal

[skrah]

I agree with "won't fix" for the original issue. These locale functions
are in effect superseded by PEP-3101 formatting.

For decimal locale specific formatting, use:

format(Decimal("1729.1415927"), "n")

IOW, I don't think new formatting functions should be added to the
locale module.

[cedk]

locale.atof is not about formatting but parsing string into float following the locale.
For now, the only ways I see to parse a string to get a Decimal is to first convert it into float (which is not good if precision matters) or to use the undocumented parameter.

[skrah]

Cédric Krier <report@bugs.python.org> wrote:

locale.atof is not about formatting but parsing string into float following the locale.

You're right. Sorry, I never use these locale functions. My impression is
that locales are often buggy or differ across platforms (see bpo-16944).

So actually I now agree that making the parameter official is one reasonable
solution.

[cedk]

Here is a patch for the documentation.

[terryjreedy]

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.