ctypes string_at/wstring_at: incorrect argument name used in docs and docstring #87969

talhayon1 · 2021-04-11T01:54:34Z

BPO	43803
Nosy	@amauryfa, @abalkin, @meadori, @eryksun, @JelleZijlstra, @shreyanavigyan
PRs	gh-87969: Amend docs and docstrings for ctypes.string_at and ctypes.wstring_at #25384

^{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 = None
created_at = <Date 2021-04-11.01:54:33.536>
labels = ['type-bug', '3.9', '3.10', '3.11', 'ctypes', 'docs']
title = 'ctypes string_at/wstring_at - bad argument name used in docs and in docstring'
updated_at = <Date 2021-06-14.10:20:50.011>
user = 'https://bugs.python.org/talhayon1'

bugs.python.org fields:

activity = <Date 2021-06-14.10:20:50.011>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'ctypes']
creation = <Date 2021-04-11.01:54:33.536>
creator = 'talhayon1'
dependencies = []
files = []
hgrepos = []
issue_num = 43803
keywords = ['patch']
message_count = 11.0
messages = ['390761', '390762', '390791', '390795', '390885', '390912', '390925', '390928', '390929', '390943', '391939']
nosy_count = 8.0
nosy_names = ['amaury.forgeotdarc', 'belopolsky', 'meador.inge', 'docs@python', 'eryksun', 'JelleZijlstra', 'shreyanavigyan', 'talhayon1']
pr_nums = ['25384']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue43803'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

talhayon1 · 2021-04-11T01:54:33Z

string_at and wstring_at first argument in docs in address but actually in code is ptr.

See

cpython/Lib/ctypes/__init__.py

Line 513 in 750f484

def string_at(ptr, size=-1):

cpython/Lib/ctypes/__init__.py

Line 525 in 750f484

def wstring_at(ptr, size=-1):

Noticed this when going over stubtest errors in typeshed.
See pull request python/typeshed#5204

JelleZijlstra · 2021-04-11T01:59:53Z

It's a bit worse: the actual name is "ptr", the function docstrings say "addr", and the documentation (https://docs.python.org/3.9/library/ctypes.html#ctypes.string_at) has "address". I'd favor updating them all to say "ptr", because changing the name of the runtime parameter would risk breaking users' code.

shreyanavigyan · 2021-04-11T19:19:38Z

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.

eryksun · 2021-04-11T21:16:09Z

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'))
    "'\\U00010000'"

Linux:

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

shreyanavigyan · 2021-04-12T18:40:32Z

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?

eryksun · 2021-04-12T21:56:44Z

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'

shreyanavigyan · 2021-04-13T06:10:25Z

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.

eryksun · 2021-04-13T06:50:29Z

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".

shreyanavigyan · 2021-04-13T06:51:48Z

Ok..then submitting the PR in 10 minutes.

shreyanavigyan · 2021-04-13T09:37:31Z

PR opened for this issue.

shreyanavigyan · 2021-04-26T14:19:02Z

Ping

…w]string_at() (#25384) The implementation uses 'ptr' for the name of the first parameter of ctypes.string_at() and ctypes.wstring_at(). Align docs and docstrings with the naming used in the implementation. Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

…pes' [w]string_at() (pythonGH-25384) The implementation uses 'ptr' for the name of the first parameter of ctypes.string_at() and ctypes.wstring_at(). Align docs and docstrings with the naming used in the implementation. (cherry picked from commit 81a926b) Co-authored-by: Shreyan Avigyan <shreyan.avigyan@gmail.com> Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

…ypes' [w]string_at() (GH-25384) (GH-118046) gh-87969: Align docs and docstrings with implementation for ctypes' [w]string_at() (GH-25384) The implementation uses 'ptr' for the name of the first parameter of ctypes.string_at() and ctypes.wstring_at(). Align docs and docstrings with the naming used in the implementation. (cherry picked from commit 81a926b) Co-authored-by: Shreyan Avigyan <shreyan.avigyan@gmail.com> Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

talhayon1 mannequin added 3.7 (EOL) end of life 3.8 (EOL) end of life 3.10 only security fixes 3.9 only security fixes topic-ctypes type-bug An unexpected behavior, bug, or error labels Apr 11, 2021

talhayon1 mannequin changed the title ~~ctypes string_at/wstring_at~~ ctypes string_at/wstring_at bad argument name Apr 11, 2021

shreyanavigyan mannequin added the docs Documentation in the Doc dir label Apr 11, 2021

shreyanavigyan mannequin changed the title ~~ctypes string_at/wstring_at bad argument name~~ ctypes string_at/wstring_at - bad argument name used in docs and in docstring Apr 11, 2021

shreyanavigyan mannequin assigned docspython Apr 11, 2021

shreyanavigyan mannequin added the docs Documentation in the Doc dir label Apr 11, 2021

shreyanavigyan mannequin changed the title ~~ctypes string_at/wstring_at bad argument name~~ ctypes string_at/wstring_at - bad argument name used in docs and in docstring Apr 11, 2021

shreyanavigyan mannequin assigned docspython Apr 11, 2021

terryjreedy removed 3.7 (EOL) end of life labels Apr 16, 2021

iritkatriel added the 3.11 only security fixes label Jun 14, 2021

iritkatriel added 3.11 only security fixes and removed 3.8 (EOL) end of life labels Jun 14, 2021

ezio-melotti transferred this issue from another repository Apr 10, 2022

erlend-aasland added 3.12 only security fixes and removed 3.11 only security fixes 3.10 only security fixes 3.9 only security fixes 3.12 only security fixes labels Jun 22, 2023

erlend-aasland changed the title ~~ctypes string_at/wstring_at - bad argument name used in docs and in docstring~~ ctypes string_at/wstring_at: incorrect argument name used in docs and docstring Jun 22, 2023

bedevere-bot mentioned this issue Jun 22, 2023

gh-87969: Amend docs and docstrings for ctypes.string_at and ctypes.wstring_at #25384

Merged

This was referenced Apr 18, 2024

[3.12] gh-87969: Align docs and docstrings with implementation for ctypes' [w]string_at() (GH-25384) #118046

Merged

[3.11] gh-87969: Align docs and docstrings with implementation for ctypes' [w]string_at() (GH-25384) #118047

Closed

encukou closed this as completed Apr 19, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

ctypes string_at/wstring_at: incorrect argument name used in docs and docstring #87969

ctypes string_at/wstring_at: incorrect argument name used in docs and docstring #87969

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ctypes string_at/wstring_at: incorrect argument name used in docs and docstring #87969

ctypes string_at/wstring_at: incorrect argument name used in docs and docstring #87969

Comments

Uh oh!

Linked PRs

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!