classification
Title: ctypes - documentation example
Type: behavior Stage: resolved
Components: ctypes Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: berker.peksag, eryksun, python-dev
Priority: normal Keywords: patch

Created on 2012-10-11 02:42 by Thorney, last changed 2016-06-02 22:18 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
ctypes_doc.diff Thorney, 2012-10-11 02:42 review
ctypes_doc.diff Thorney, 2012-10-11 07:36 review
Messages (10)
msg172616 - (view) Author: Brian Thorne (Thorney) Date: 2012-10-11 02:42
The Python docs for ctypes have embedded examples including:

>>> c_int()
c_long(0)

But on my machine I get the (more expected?):

>>> c_int()
c_int(0)

Perhaps if some machines expect otherwise that should be documented, otherwise might we change them.
msg172624 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-11 07:21
> Perhaps if some machines expect otherwise that should be documented, otherwise might we change them.

The very beginning of the ctypes documentation has documentation to that effect:

"Note: Some code samples reference the ctypes c_int type. This type is an alias for the c_long type on 32-bit systems. So, you should not be confused if c_long is printed if you would expect c_int — they are actually the same type."

http://docs.python.org/dev/library/ctypes.html#ctypes-tutorial

Does that address your suggestion?
msg172625 - (view) Author: Brian Thorne (Thorney) Date: 2012-10-11 07:36
> The very beginning of the ctypes documentation has documentation to that effect

>Does that address your suggestion?

Thanks Chris, that explains why the difference is present on non 32 bit platforms. Would using c_long for the examples produce the expected output on 64 and 32 bit systems? 

Just an idea to try remove potential confusion.
msg172626 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-11 07:51
I don't know off-hand.  But maybe an additional note or code comment at the first instance in a code example would help.  Switching the examples to c_long might serve only to shift potential confusion from the examples to someone's personal machine.
msg172735 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-12 09:41
The note at the beginning could be turned in an actual note using the `.. note:` markup.  This will make it more visible.
msg233751 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2015-01-09 13:08
It's not correct that "[The c_int] type is an alias for the c_long type on 32-bit systems". Actually it's an alias if int and long are the same size. Here's the relevant snippet from __init__:

    if _calcsize("i") == _calcsize("l"):
        # if int and long have the same size, make c_int an alias for c_long
        c_int = c_long
        c_uint = c_ulong
    else:
        class c_int(_SimpleCData):
            _type_ = "i"
        _check_size(c_int)

        class c_uint(_SimpleCData):
            _type_ = "I"
        _check_size(c_uint)

Notably, int and long are the same size on 64-bit Windows:

    >>> sizeof(c_void_p) # 64-bit
    8
    >>> c_int                    
    <class 'ctypes.c_long'>
    >>> sizeof(c_long)           
    4
msg233765 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2015-01-09 16:42
> It's not correct that "[The c_int] type is an alias for the c_long type on 32-bit systems". Actually it's an alias if int and long are the same size.

It's already documented at https://docs.python.org/dev/library/ctypes.html#ctypes.c_int

    "On platforms where sizeof(int) == sizeof(long) it is an alias to c_long."

Do you want to write a patch to update the original note?
msg266922 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-06-02 19:08
New changeset 1775abf47061 by Berker Peksag in branch '3.5':
Issue #16192: Clarify when c_int is an alias to c_long in ctypes documentation
https://hg.python.org/cpython/rev/1775abf47061

New changeset 9954e29b8678 by Berker Peksag in branch 'default':
Issue #16192: Merge from 3.5
https://hg.python.org/cpython/rev/9954e29b8678
msg266965 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2016-06-02 21:55
> ``sizeof(long double) == sizeof(double)`` it is an alias to
> :class:`c_double`.  

This should be "``sizeof(long) == sizeof(int)`` ... :class:`c_long`".
msg266975 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-06-02 22:18
New changeset dfde53cf07e6 by Berker Peksag in branch '3.5':
Issue #16192: Fix copy and paste mistake noticed by Eryk Sun
https://hg.python.org/cpython/rev/dfde53cf07e6

New changeset 7f3ebd86464b by Berker Peksag in branch 'default':
Issue #16192: Merge from 3.5
https://hg.python.org/cpython/rev/7f3ebd86464b
History
Date User Action Args
2016-06-02 22:18:58berker.peksagsetstatus: open -> closed
resolution: fixed
stage: resolved
2016-06-02 22:18:28python-devsetmessages: + msg266975
2016-06-02 21:55:45eryksunsetstatus: closed -> open
resolution: fixed -> (no value)
messages: + msg266965

stage: resolved -> (no value)
2016-06-02 19:09:22berker.peksagsetstatus: open -> closed
stage: needs patch -> resolved
resolution: fixed
versions: + Python 3.6, - Python 3.4
2016-06-02 19:08:10python-devsetnosy: + python-dev
messages: + msg266922
2015-01-09 16:42:49berker.peksagsetstatus: closed -> open
versions: + Python 3.5
nosy: + berker.peksag

messages: + msg233765

stage: needs patch
2015-01-09 13:08:32eryksunsetnosy: + eryksun
messages: + msg233751
2015-01-09 04:01:18Thorneysetstatus: open -> closed
nosy: - georg.brandl, ezio.melotti, eric.araujo, Thorney, chris.jerdonek
-> (no value)
2012-10-12 09:41:02ezio.melottisetmessages: + msg172735
2012-10-11 07:51:25chris.jerdoneksetmessages: + msg172626
2012-10-11 07:36:11Thorneysetfiles: + ctypes_doc.diff
status: pending -> open
messages: + msg172625
2012-10-11 07:21:03chris.jerdoneksetstatus: open -> pending
nosy: + chris.jerdonek
messages: + msg172624

2012-10-11 02:42:49Thorneycreate