[issue13918] locale.atof documentation is missing func argument
New submission from Cédric Krier <cedric.krier@b2ck.com>: atof has a func argument used to instantiate the result but it is missing in the documentation. ---------- assignee: docs@python components: Documentation messages: 152430 nosy: ced, docs@python priority: normal severity: normal status: open title: locale.atof documentation is missing func argument type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Georg Brandl <georg@python.org> added the comment: 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. ---------- nosy: +georg.brandl resolution: -> wont fix status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Cédric Krier <cedric.krier@b2ck.com> added the comment: 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? ---------- status: pending -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Ezio Melotti added the comment: 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. ---------- nosy: +ezio.melotti status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Cédric Krier added the comment: Then I think we miss a locale.atod to parse string to Decimal ---------- status: pending -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +mark.dickinson, skrah _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Stefan Krah added the comment: 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. ---------- status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Cédric Krier added the comment: 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. ---------- status: closed -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Stefan Krah added the comment: 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 #16944). So actually I now agree that making the parameter official is one reasonable solution. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Cédric Krier added the comment: Here is a patch for the documentation. ---------- keywords: +patch resolution: wont fix -> Added file: http://bugs.python.org/file29414/doc_atof.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Terry J. Reedy added the comment: 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. ---------- nosy: +terry.reedy versions: +Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Ezio Melotti added the comment: The function was introduced by Guido in f5b55311e79d. I think it would have been better if atof had another name (e.g. _atof) and that atof and atoi were implemented as: def atof(str): return _atof(str, float) def atoi(str): return _atof(str, int) Even better would have been to have _atof return the string without applying any function, and let e.g. atoi return int(_atof(str)). This could have been documented publicly and used to build other functions. However it's probably too late for such refactoring. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Terry J. Reedy added the comment: The refactoring could be done if we were willing to give the normalize function a public name, so people could write Decimal(delocalize(<localized float string>)) or if we were willing to add atod and atofr (fraction). However, simply adding a few words to the doc is a lot easier. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Ezio Melotti added the comment: It's easier, but we will be exposing an API that is not too elegant IMHO. The refactoring could provide a better API, but OTOH it will make it available for 3.4+ only, and it would break backward compatibility if the old API is removed (even though it's not documented, so in theory we could do that). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Changes by Stefan Krah <stefan-usenet@bytereef.org>: ---------- nosy: -skrah _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Cédric Krier added the comment: So what about this patch? It adds a delocalize method while keeping the atof func parameter for backward compatibility. ---------- Added file: http://bugs.python.org/file36955/delocalize.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Changes by Antoine Pitrou <pitrou@free.fr>: ---------- assignee: docs@python -> components: +Library (Lib) -Documentation stage: -> patch review versions: +Python 3.5 -Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Antoine Pitrou added the comment: The patch's approach looks reasonable to me. ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Cédric Krier added the comment: A new version with unittest. ---------- Added file: http://bugs.python.org/file36960/delocalize.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Antoine Pitrou added the comment: Thanks for the updated patch, Cédric. Just some remarks: - the documentation should mention that the return value is still a string - the documentation needs a "versionadded" marker next to the new function - have you already signed the contributor's agreement? otherwise you should sign it at https://www.python.org/psf/contrib/contrib-form/ ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Cédric Krier added the comment: Add return value is string in doc Add versionadded And yes I signed the agreement. ---------- Added file: http://bugs.python.org/file36964/delocalize.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Antoine Pitrou added the comment: Thank you! The patch looks good to me, I'm going to apply it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Roundup Robot added the comment: New changeset aee097e5a2b2 by Antoine Pitrou in branch 'default': Issue #13918: Provide a locale.delocalize() function which can remove https://hg.python.org/cpython/rev/aee097e5a2b2 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Antoine Pitrou added the comment: Done. Thank you for your contribution! ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
STINNER Victor added the comment: + :const:'LC_NUMERIC`settings. a space is missing before "settings", no? ---------- nosy: +haypo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Antoine Pitrou added the comment: Ah, right, thank you. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
Georg Brandl added the comment: And the first quote is wrong. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________
participants (8)
-
Antoine Pitrou -
Cédric Krier
-
Ezio Melotti
-
Georg Brandl
-
Roundup Robot
-
Stefan Krah
-
STINNER Victor
-
Terry J. Reedy