[issue16801] Preserve original representation for integers / floats in docstrings

Change by Mark Dickinson : -- nosy: -mark.dickinson ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue16801] Preserve original representation for integers / floats in docstrings

Mark Dickinson added the comment: FWIW, the relevant change seems to be this one: https://github.com/sphinx-doc/sphinx/pull/7155 -- ___ Python tracker ___

[issue16801] Preserve original representation for integers / floats in docstrings

Mark Dickinson added the comment: I suspect the difference is due to a change in the way that Sphinx handles the py:method directive: the rst source for `pathlib.Path.touch` hasn't changed between 3.9 and 3.10, but the 3.9 docs are built with Sphinx 2.4.4, while the 3.10 docs are built with

[issue16801] Preserve original representation for integers / floats in docstrings

Éric Araujo added the comment: Please open a ticket! This one is about docstrings and pydoc; docs.python.org is built from rst docs with sphinx. -- versions: +Python 3.11 -Python 3.4 ___ Python tracker

[issue16801] Preserve original representation for integers / floats in docstrings

Scott Stevens added the comment: I'm now seeing docs.python.org has regressed. For 3.9, calls present their defaults in octal, in 3.10 (beta), they're presented in decimal. https://docs.python.org/3.10/library/pathlib.html#pathlib.Path.touch

[issue16801] Preserve original representation for integers / floats in docstrings

Change by Batuhan Taskaya : -- nosy: +pablogsal ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue16801] Preserve original representation for integers / floats in docstrings

Batuhan Taskaya added the comment: I'm very late to join this thread, but since the Constant() node has now a kind field, we can possibly add this (though I'm not saying we should, depending on whether still this would be a nice addition to clinic docstrings.) 2 options that I can think

[issue16801] Preserve original representation for integers / floats in docstrings

Changes by Éric Araujo mer...@netwok.org: -- nosy: +eric.araujo ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16801 ___ ___ Python-bugs-list

[issue16801] Preserve original representation for integers / floats in docstrings

Serhiy Storchaka added the comment: It's cumbersome and burdensome because you need for every nonstandard default value: 1) define a class with __repr__(); 2) instantiate a sentinel; 3) check for the sentinel in the function and replace it but an actual value. class _ExternalAttrDefault:

[issue16801] Preserve original representation for integers / floats in docstrings

Serhiy Storchaka added the comment: It's particular because there are functions whose signatures can't be expressed with valid Python syntax (dict, range, operator.methodcaller, many curses functions). They required other solution and this more general solution is applicable for the problem

[issue16801] Preserve original representation for integers / floats in docstrings

Terry J. Reedy added the comment: Your indeed cumbersome and overly specific process has almost nothing to do with what I proposed and gave two examples of. Please reread and understand msg178542 before you criticize it. Class octint pythonically solves the octal mode display problem that

[issue16801] Preserve original representation for integers / floats in docstrings

Larry Hastings added the comment: FWIW I think the octint class is a great idea. It's nice and localized, and it should have no performance impact and only a small maintenance impact. It'll also preserve the readability of the default if you pull it out with inspect.getfullargspec /

[issue16801] Preserve original representation for integers / floats in docstrings

Terry J. Reedy added the comment: Sorry, as with all similar subclasses, class op subclass = class unless one explicitly subclasses the answer or overrides the __op__ method to do that for you. class octint(int): 'int that displays as octal' def __str__(self): return oct(self)

[issue16801] Preserve original representation for integers / floats in docstrings

R. David Murray added the comment: Note: Nick Coghlan's idea of having Named Value support in Python just came up again on python-dev, and this would be a perfect application for it (pretty much exactly Terry's proposal in msg178542). -- ___ Python

[issue16801] Preserve original representation for integers / floats in docstrings

Changes by Barry A. Warsaw ba...@python.org: -- nosy: +barry ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16801 ___ ___ Python-bugs-list mailing

[issue16801] Preserve original representation for integers / floats in docstrings

Terry J. Reedy added the comment: Serhiy called subclassing 'particular and cumbersome'. 'Cumbersome' is an opinion. I consider subclassing elegant. The ease of doing so and specializing only what one needs to is a major feature of Python. It only took me a couple of minutes to whip up

[issue16801] Preserve original representation for integers / floats in docstrings

Georg Brandl added the comment: For example, any function where an argument has a sentinel object as the default value, such as socket.create_connection(). -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16801

[issue16801] Preserve original representation for integers / floats in docstrings

Larry Hastings added the comment: Georg: what other functions do you know of where (as you suggest) the signature could be improved? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16801

[issue16801] Preserve original representation for integers / floats in docstrings

Serhiy Storchaka added the comment: A subclass with a custom representation, as I suggested above, is even simpler and involves no change to inspect or docstring conventions. Agree, but this is a particular and cumbersome solution. I open new issue16842 for docstring conventions. --

[issue16801] Preserve original representation for integers / floats in docstrings

Ezio Melotti added the comment: Either repeating the default value in the text with the desired form (and leave it wrong in the signature) or what Georg suggested in msg178519 sound good to me. I don't think anything more than that is necessary to solve this issue. --

[issue16801] Preserve original representation for integers / floats in docstrings

Terry J. Reedy added the comment: A subclass with a custom representation, as I suggested above, is even simpler and involves no change to inspect or docstring conventions. I otherwise agree with closing this. -- ___ Python tracker

[issue16801] Preserve original representation for integers / floats in docstrings

Georg Brandl added the comment: 20+ years of Python success suggest this isn't a problem that needs solving. That reasoning could be applied to almost all open tracker issues. Likewise, Linux itself doesn't preserve the original form of a chmod call. Where would/could it do so? C has no

[issue16801] Preserve original representation for integers / floats in docstrings

Changes by Ezio Melotti ezio.melo...@gmail.com: -- nosy: +ezio.melotti ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16801 ___ ___

[issue16801] Preserve original representation for integers / floats in docstrings

Raymond Hettinger added the comment: 20+ years of Python success suggest this isn't a problem that needs solving. AFAICT, other languages haven't found a need to preserve number representation either. Likewise, Linux itself doesn't preserve the original form of a chmod call. I recommend

[issue16801] Preserve original representation for integers / floats in docstrings

Carsten Klein added the comment: The problem with this is that at the time that pydoc gets the information via inspect, the numbers have already been parsed as long or double and the original notation is no longer available. This is due to the fact that during build of the AST node for the

[issue16801] Preserve original representation for integers / floats in docstrings

Carsten Klein added the comment: Here are some links into the sources: Python/ast.c, ast_for_atom(), line 1872ff. Python/ast.c, parsenumber(), line 3632ff. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16801

[issue16801] Preserve original representation for integers / floats in docstrings

Carsten Klein added the comment: However, hinting inspect to use a different format when serializing the default values for existing keyword parameters of methods or functions seems to be a good idea and +1 by me for that. Personally, I'd rather have the decorator based solution than having to

[issue16801] Preserve original representation for integers / floats in docstrings

Serhiy Storchaka added the comment: And if os.open were supplied in os.py: @inspect.override_string_representation('mode', 'os.O_CREAT | os.O_RDWR') def open(file, flags, mode=0o777, *, dir_fd=None): Other use case is a sentinel default. foo(arg={}) looks better than

[issue16801] Preserve original representation for integers / floats in docstrings

Georg Brandl added the comment: A simple, minimal-invasive solution would be to allow a signature for documentation purposes as the first line of the docstrings. pydoc could recognize this (if docstring.startswith(func.__name__ + '(') or something like that), and display the given signature

[issue16801] Preserve original representation for integers / floats in docstrings

Serhiy Storchaka added the comment: pydoc could recognize this (if docstring.startswith(func.__name__ + '(') or something like that), and display the given signature instead of the introspected one. Looks good for me. -- ___ Python tracker

[issue16801] Preserve original representation for integers / floats in docstrings

Terry J. Reedy added the comment: It seems to me that the real issue is not to preserve the original representation. What if the original author specified mode as 438 or calculated it as 0o600|0o60|0o6 ? He might and we should still like to see it as 0o666. So the real issue is to specify the

[issue16801] Preserve original representation for integers / floats in docstrings

New submission from Larry Hastings: The line declaring the function dbm.open looks like this: def open(file, flag='r', mode=0o666): The docstring for dbm.open looks like this: open(file, flag='r', mode=438) Obviously 438==0o666. But the author used the octal representation because

[issue16801] Preserve original representation for integers / floats in docstrings

Larry Hastings added the comment: (I was also considering proposing using annotations to tell the parser we want the original representation in the docstring, but I suspect that's a bad idea. That would instantly restrict the untamed frontier that is annotations.) --

[issue16801] Preserve original representation for integers / floats in docstrings

Mark Dickinson added the comment: It's an interesting idea. This sounds like the wrong solution to me, though: it's significant extra machinery to produce a solution that only fixes a small handful of cases; IOW, the benefit / cost ratio seems to small to make this worth it. E.g., apart

[issue16801] Preserve original representation for integers / floats in docstrings

R. David Murray added the comment: I don't think you mean 'docstring'. A docstring is something a human writes in the source code. I presume you are actually talking about introspection of the signature here. Beyond that, I agree with Mark's comments. -- nosy: +r.david.murray

[issue16801] Preserve original representation for integers / floats in docstrings

Mark Dickinson added the comment: BTW, in case it saves anyone else some time, the current machinery is in Lib/pydoc.py, in the `TextDoc.docroutine` method. It uses inspect.getfullargspec to retrieve the information to format, though I guess using inspect.Signature would be the modern way to

[issue16801] Preserve original representation for integers / floats in docstrings

Mark Dickinson added the comment: Bah. s/inspect.Signature/inspect.signature/ -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16801 ___ ___

[issue16801] Preserve original representation for integers / floats in docstrings

Terry J. Reedy added the comment: David is correct dbm.open.__doc__ Open or create database at path given by *file*.\n\nOptional argument *flag* can be 'r' (default) for read-only access, 'w'\nfor read-write access of an existing database, 'c' for read-write access\nto a new or

[issue16801] Preserve original representation for integers / floats in docstrings

Larry Hastings added the comment: Okay, counter-proposal time. We add a new field to the Parameter object, the preferred string representation of the default. If the parameter has a default, it is always a string, by default repr(parameter_default_value); if the parameter has no default

[issue16801] Preserve original representation for integers / floats in docstrings

Changes by Arfrever Frehtes Taifersar Arahesis arfrever@gmail.com: -- nosy: +Arfrever ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16801 ___

[issue16801] Preserve original representation for integers / floats in docstrings

Terry J. Reedy added the comment: If you wish to pursue this, I suggest starting with 'the simplest thing that works' for the text cases at hand. They all involve 'mode' and you have not presented and I cannot think of other cases. So somewhere in the signature generation code: if function