[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Irit Katriel]

Change by Irit Katriel :


--
versions: +Python 3.11 -Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Shreyan Avigyan]

Shreyan Avigyan  added the comment:

Ping

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Shreyan Avigyan]

Change by Shreyan Avigyan :


--
nosy: +amaury.forgeotdarc, belopolsky, meador.inge

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Terry J. Reedy]

Change by Terry J. Reedy :


--
versions:  -Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Shreyan Avigyan]

Shreyan Avigyan  added the comment:

PR opened for this issue.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Shreyan Avigyan]

Change by Shreyan Avigyan :


--
keywords: +patch
pull_requests: +24116
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/25384

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Shreyan Avigyan]

Shreyan Avigyan  added the comment:

Ok..then submitting the PR in 10 minutes.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Eryk Sun]

Eryk Sun  added the comment:

> So are you telling that we should change the name to "ptr" to 
> avoid a breaking change?

The function parameter name is "ptr". Changing that name could break existing 
code. I don't think it's likely, but it's not worth breaking even one script 
just for this. So change the docstring and documentation to refer to "ptr".

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Shreyan Avigyan]

Shreyan Avigyan  added the comment:

Ok...let me review again. Having different names for the same argument can 
cause confusion, right? So are you telling that we should change the name to 
"ptr" to avoid a breaking change?

If this issue is confirmed, I'm ready to submit a PR to make this change.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Eryk Sun]

Eryk Sun  added the comment:

> If that's the problem then why not change all of them to use the 
> name "address" or "addr" to avoid confusion and make it clear 
> simple. What is your view?

Change them all to refer to `ptr`. It's not worth introducing a breaking change:

>>> ctypes.string_at(ptr=b'spam')
b'spam'

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Shreyan Avigyan]

Shreyan Avigyan  added the comment:

Yeah, you're right and also it is true that changing the docstring to "ptr" can 
succinctly say "Return the byte string at void *ptr." But it's a kind of 
problem if different argument names are used for the same argument in 
docstring, argument list and documentation. If that's the problem then why not 
change all of them to use the name "address" or "addr" to avoid confusion and 
make it clear simple. What is your view?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Eryk Sun]

Eryk Sun  added the comment:

> the name "address" and "addr" respectively which are misleading 
> because it is asking for ctypes.c_char_p or ctypes.c_wchar_p which 
> are C pointer types

string_at() and wstring_at() take a c_void_p value. This can be initialized by 
an integer (i.e. an address), bytes, str, or any ctypes pointer, array, or 
byref() reference. 

Additionally it works with an object that has a compatible _as_parameter_ 
attribute, e.g.:

>>> class A:
..._as_parameter_ = b'spam'
... 
>>> ctypes.string_at(A)
b'spam'

If the docstring is change to use "ptr", for string_at() it can succinctly say 
the following: "Return the byte string at void *ptr." 

For wstring_at(), replace "byte string" with "wide-character string" or 
"wchar_t string". Specifying the type matters because it depends on the 
platform. Windows uses a 16-bit wchar_t, and the memory will be interpreted as 
UTF-16 (e.g. surrogate pairs), whereas other platforms use a 32-bit wchar_t, 
and the memory will be interpreted as UTF-32. For example:

Windows:

>>> ascii(ctypes.wstring_at(b'\x00\xd8\x00\xdc'))
"'\\U0001'"

Linux:

>>> try: ctypes.wstring_at(b'\x00\xd8\x00\xdc')
... except Exception as e: print(e)
... 
character U+dc00d800 is not in range [U+; U+10]

--
nosy: +eryksun

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43803] ctypes string_at/wstring_at - bad argument name used in docs and in docstring

[Shreyan Avigyan]

Shreyan Avigyan  added the comment:

> I'd favor updating them all to say "ptr", because changing the name of the 
> runtime parameter would risk breaking users' code.

I also certainly agree with that. Moreover, the documentation and docstring 
uses the name "address" and "addr" respectively which are misleading because it 
is asking for ctypes.c_char_p or ctypes.c_wchar_p which are C pointer types, it 
is not asking for the address of instances of ctypes.c_char_p or 
ctypes.c_wchar_p. Therefore a change in the documentation and docstring is 
required.

Note - If this issue is confirmed then I'll submit a PR to apply the change as 
described in this issue.

--
assignee:  -> docs@python
components: +Documentation
nosy: +docs@python, shreyanavigyan
title: ctypes string_at/wstring_at bad argument name -> ctypes 
string_at/wstring_at - bad argument name used in docs and in docstring

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com