[Python-Dev] Re: Signature discrepancies between documentation and implementation
> On 10 Feb 2021, at 01:28, Petr Viktorin wrote: > > On 2/9/21 9:15 PM, Serhiy Storchaka wrote: >> 09.02.21 12:22, Erlend Aasland пише: >>> What's the recommended approach with issues like >>> https://bugs.python.org/issue43094? Change the docs or the implementation? >>> I did a quick search on bpo, but could not find similar past issues. >> If the documentation and the C implemented function contradict about >> parameter name, we are free to treat the parameter as positional-only. >> User cannot pass the argument as keyword because the documented name >> does not work, and the real name is not exposed to the user. > > It is. Python will correct you if you try to use the documented name: Correct. However, I suspect that most users use positional arguments with these functions (since this is the first (?) report of the inconsistency) so I guess it's ok, in this case, to make the arguments positional only and normalise the argument naming. Erlend ___ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/4U3IYJE5ZAXJQWHPXCQZC2K4OYDZWVFE/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Signature discrepancies between documentation and implementation
Thanks, Jakub. E > On 9 Feb 2021, at 19:42, Jakub Stasiak wrote: > > To provide some context as you looked for issues on bpo: in the two I was > involved in[1][2] the resolution was to update the documenttion to reflect > the actual situation. > > Best, > Jakub > > [1] https://bugs.python.org/issue42230 > [2] https://bugs.python.org/issue38580 > ___ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/UJJ7CKQ6QYYVLBCUJPT4TUSTYTWFADDT/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Signature discrepancies between documentation and implementation
On 2/9/21 9:15 PM, Serhiy Storchaka wrote:
09.02.21 12:22, Erlend Aasland пише:
What's the recommended approach with issues like
https://bugs.python.org/issue43094? Change the docs or the implementation? I
did a quick search on bpo, but could not find similar past issues.
If the documentation and the C implemented function contradict about
parameter name, we are free to treat the parameter as positional-only.
User cannot pass the argument as keyword because the documented name
does not work, and the real name is not exposed to the user.
It is. Python will correct you if you try to use the documented name:
>>> import sqlite3
>>> connection = sqlite3.connect(':memory:')
>>> connection.create_function('testfunc', num_params=1, func=lambda
arg: None)
Traceback (most recent call last):
File "", line 1, in
TypeError: function missing required argument 'narg' (pos 2)
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at
https://mail.python.org/archives/list/python-dev@python.org/message/UHDNIUTPS6FESF2VRK5AJMHUZIDKZL2N/
Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Signature discrepancies between documentation and implementation
On Tue., Feb. 9, 2021, 12:20 Serhiy Storchaka, wrote: > 09.02.21 12:22, Erlend Aasland пише: > > What's the recommended approach with issues like > https://bugs.python.org/issue43094? Change the docs or the > implementation? I did a quick search on bpo, but could not find similar > past issues. > > If the documentation and the C implemented function contradict about > parameter name, we are free to treat the parameter as positional-only. > User cannot pass the argument as keyword because the documented name > does not work, and the real name is not exposed to the user. > I agree with Serhiy's logic. -Brett > In this case, there are two similar functions, create_function() and > create_aggregate(). Both are documented as having parameter > "num_params", but real names are different: "narg" and "n_arg". It would > be confusing to have different spelling of the same parameter in similar > functions. I am sure that it would be difficult to remember how is it > spelled in every case. Also, in Python terminology, the semantic of this > name is the number of parameters, not the number of argument. > > So I think that in this particular case the chance of breaking some code > is insignificant, but possible long-term harm of exposing bad parameter > names may be significant. > ___ > Python-Dev mailing list -- python-dev@python.org > To unsubscribe send an email to python-dev-le...@python.org > https://mail.python.org/mailman3/lists/python-dev.python.org/ > Message archived at > https://mail.python.org/archives/list/python-dev@python.org/message/JE2E5RJZQPMXHTWIU3NA74YDMEZHGYUK/ > Code of Conduct: http://python.org/psf/codeofconduct/ > ___ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/L5KVZMBF6VDLA42KRODHCGNKIGGEMIVL/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Signature discrepancies between documentation and implementation
09.02.21 12:22, Erlend Aasland пише: > What's the recommended approach with issues like > https://bugs.python.org/issue43094? Change the docs or the implementation? I > did a quick search on bpo, but could not find similar past issues. If the documentation and the C implemented function contradict about parameter name, we are free to treat the parameter as positional-only. User cannot pass the argument as keyword because the documented name does not work, and the real name is not exposed to the user. In this case, there are two similar functions, create_function() and create_aggregate(). Both are documented as having parameter "num_params", but real names are different: "narg" and "n_arg". It would be confusing to have different spelling of the same parameter in similar functions. I am sure that it would be difficult to remember how is it spelled in every case. Also, in Python terminology, the semantic of this name is the number of parameters, not the number of argument. So I think that in this particular case the chance of breaking some code is insignificant, but possible long-term harm of exposing bad parameter names may be significant. ___ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/JE2E5RJZQPMXHTWIU3NA74YDMEZHGYUK/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Signature discrepancies between documentation and implementation
> On 9 Feb 2021, at 11:22, Erlend Aasland wrote: > > Hi all, > > What's the recommended approach with issues like > https://bugs.python.org/issue43094? Change the docs or the implementation? I > did a quick search on bpo, but could not find similar past issues. > > > > Erlend To provide some context as you looked for issues on bpo: in the two I was involved in[1][2] the resolution was to update the documenttion to reflect the actual situation. Best, Jakub [1] https://bugs.python.org/issue42230 [2] https://bugs.python.org/issue38580 ___ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/FHWE3YHZNZE7QRTSH5FA4Z7A2LQUBROB/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Signature discrepancies between documentation and implementation
Hi Victor, and thanks for you reply. > On 9 Feb 2021, at 11:46, Victor Stinner wrote: > If there are applications relying on the parameter name, it's better > to trust the Python implementation, rather than the documentation. I feared that answer :) > It would be better to make these parameters positional only in the > first place, but now it's too late for such backward incompatible > change :-( Unfortunately, yes. Erlend ___ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/7XJMO335TVWAUZWXLOH6272E5K5FJL7N/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Signature discrepancies between documentation and implementation
If there are applications relying on the parameter name, it's better to trust the Python implementation, rather than the documentation. It would be better to make these parameters positional only in the first place, but now it's too late for such backward incompatible change :-( Victor On Tue, Feb 9, 2021 at 11:43 AM Erlend Aasland wrote: > > Hi all, > > What's the recommended approach with issues like > https://bugs.python.org/issue43094? Change the docs or the implementation? I > did a quick search on bpo, but could not find similar past issues. > > > > Erlend > ___ > Python-Dev mailing list -- python-dev@python.org > To unsubscribe send an email to python-dev-le...@python.org > https://mail.python.org/mailman3/lists/python-dev.python.org/ > Message archived at > https://mail.python.org/archives/list/python-dev@python.org/message/3NPQMMWIDSP5DEBV5LAQ3Y7JUIUN4PFE/ > Code of Conduct: http://python.org/psf/codeofconduct/ -- Night gathers, and now my watch begins. It shall not end until my death. ___ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/X6SZIVOZ233TLLJV43UQEHMV3ELGP34S/ Code of Conduct: http://python.org/psf/codeofconduct/
