classification
Title: Document ctypes.wintypes constants
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: amaury.forgeotdarc, docs@python, markm, orsenthil, techtonik
Priority: normal Keywords:

Created on 2011-02-20 06:13 by techtonik, last changed 2017-11-08 15:17 by berker.peksag.

Messages (6)
msg128893 - (view) Author: anatoly techtonik (techtonik) Date: 2011-02-20 06:13
I've just noticed that my application is incompatible with Python 2.5, because ctypes.wintypes is missing SHORT constants. However, I can't find the information when these symbols were introduced first. To prevent such confusion in future it would be nice to extract symbol information for each Python release and automatically include the version of the first appearance in documentation.
msg129371 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2011-02-25 14:24
Can you provide a patch, or show how to do it concretely?
msg139165 - (view) Author: Mark Mc Mahon (markm) * Date: 2011-06-26 10:44
This mostly a documentation concern - correct? ctypes.wintypes is sparsely documented - in 2.7 the help for it seems to be:
"The ctypes.wintypes module provides quite some other Windows specific data types, for example HWND, WPARAM, or DWORD. Some useful structures like MSG or RECT are also defined."

How about the following solution:
First of all get the previous release information
 - hg log / hg revert / import wintypes / dir(wintypes)

Future changes have to be updated manually (which probably is not a big deal as it is a reasonably stable module)

In fact I went and got the revision when each attribute was added... (some of those are just ctypes leakage)
{36899: ['ARRAY',                   'MSG',
         'ArgumentError',           'OLESTR',
         'Array',                   'OleDLL',
         'BOOL',                    'POINT',
         'BYTE',                    'POINTER',
         'BigEndianStructure',      'POINTL',
         'DEFAULT_MODE',            'PYFUNCTYPE',
         'DWORD',                   'PyDLL',
         'FILETIME',                'RECT',
         'FormatError',             'RECTL',
         'GetLastError',            'RGB',
         'HANDLE',                  'RTLD_GLOBAL',
         'HDC',                     'RTLD_LOCAL',
         'HGDIOBJ',                 'SIZE',
         'HINSTANCE',               'SIZEL',
         'HKEY',                    'SetPointerType',
         'HMENU',                   'Structure',
         'HMODULE',                 'ULARGE_INTEGER',
         'HPEN',                    'ULONG',
         'HRESULT',                 'Union',
         'HRGN',                    'VARIANT_BOOL',
         'HTASK',                   'WIN32_FIND_DATAA',
         'HWND',                    'WIN32_FIND_DATAW',
         'LARGE_INTEGER',           'WINFUNCTYPE',
         'LCID',                    'WORD',
         'LONG',                    'WPARAM',
         'LPARAM',                  'WinDLL',
         'LPCOLESTR',               'WinError',
         'LPCSTR',                  'alignment',
         'LPCWSTR',                 'get_errno',
         'LPOLESTR',                'get_last_error',
         'LPSTR',                   'resize',
         'LPWSTR',                  'set_conversion_mode',
         'LibraryLoader',           'set_errno',
         'LittleEndianStructure',   'set_last_error',
         'MAX_PATH',]

 38788: ['ATOM',                     'HRSRC',
         'BOOLEAN',                  'HSTR',
         'COLORREF',                 'HWINSTA',
         'HACCEL',                   'LANGID',
         'HBITMAP',                  'LCTYPE',
         'HBRUSH',                   'LGRPID',
         'HCOLORSPACE',              'SC_HANDLE',
         'HDESK',                    'SERVICE_STATUS_HANDLE',
         'HDWP',                     'SMALL_RECT',
         'HENHMETAFILE',             '_COORD',
         'HFONT',                    '_FILETIME',
         'HGLOBAL',                  '_POINTL',
         'HHOOK',                    '_RECTL',
         'HICON',                    '_SMALL_RECT',
         'HKL',                      'tagMSG',
         'HLOCAL',                   'tagPOINT',
         'HMETAFILE',                'tagRECT',
         'HMONITOR',                 'tagSIZE',
         'HPALETTE',]

 38830: ['DOUBLE',
         'UINT',
         'WCHAR',
         '_LARGE_INTEGER',
         '_SimpleCData',
         '_ULARGE_INTEGER',
         '__all__'],

 48320: ['FLOAT',
         'INT',
         'LPCVOID',
         'LPVOID',
         'SHORT',
         'USHORT']}

48320 -> 2.7?
38830 -> 2.5?
38788 -> 2.5?
36899 -> 2.4?

So we need a doc patch? Should we update the older 'What's new in Python 2.x' for added attribs?
msg139226 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-06-26 21:18
On Sun, Jun 26, 2011 at 10:44:59AM +0000, Mark Mc Mahon wrote:
> So we need a doc patch? Should we update the older 'What's new in
> Python 2.x' for added attribs?

The Documentation patch may be applied only 2.7 and 3.2/3.3 releases
now. What's new is updated for the upcoming release only.

So, if documenting those constants will help in 2.7.x and 3.2.x and
3.3, it would be helpful to provide patches against those lines and it
can be applied. As you said, the future version can be updated, but we
cannot go back with updating the documentation of the already released
versions.
msg139669 - (view) Author: anatoly techtonik (techtonik) Date: 2011-07-03 05:32
On Mon, Jun 27, 2011 at 12:18 AM, Senthil Kumaran
<report@bugs.python.org> wrote:
> As you said, the future version can be updated, but we
> cannot go back with updating the documentation of the already released
> versions.

Why?
--
anatoly t.
msg139702 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-07-03 20:10
What's new docs are usually for what is coming up new in the upcoming
releases. It is not updated once the release is done. Bug fixes and
related docs are updated in documentation.
History
Date User Action Args
2017-11-08 15:17:57berker.peksagsettitle: autodocument first appearance of ctypes.wintypes constants -> Document ctypes.wintypes constants
stage: needs patch
type: enhancement
versions: + Python 3.6, Python 3.7, - Python 3.3
2011-07-03 20:10:03orsenthilsetmessages: + msg139702
2011-07-03 05:32:10techtoniksetmessages: + msg139669
2011-06-26 21:18:31orsenthilsetnosy: + orsenthil
messages: + msg139226
2011-06-26 10:44:58markmsetnosy: + markm
messages: + msg139165
2011-02-25 22:55:45eric.araujosetnosy: amaury.forgeotdarc, techtonik, docs@python
versions: - Python 2.6, Python 2.5, Python 3.1, Python 2.7, Python 3.2
2011-02-25 14:24:34amaury.forgeotdarcsetnosy: + amaury.forgeotdarc
messages: + msg129371
2011-02-20 06:13:45techtonikcreate