pywin32
pywin32 copied to clipboard
mhammond
No documentation of top-level package/module hierarchy
This project produces a dizzying panoply of top-level modules, including win32, win32com, pythoncom, and pywintypes, but does not provide any overview of them. There is no documentation of the top-level hierarchy at all.
The README is silent. The PyPI page is barren. Calling help(pythoncom) literally crashes python. This website makes no effort to distinguish submodules (like win32com's propsys) from top-level modules (like pythoncom), and provides no location for some types (like com_error).
Should com_error be imported from pywintypes or pythoncom? It doesn't say. Why are pythoncom and win32com separate packages? It doesn't say, and asking crashes python.
Please clearly explain the package hierarchy, and the intended locations from which to import types.
I recently discovered Pywin32. I would like to learn more about it. The first thing I looked for was some mention in readme.md of where to find documentation. I don't see it, and I think this absence is a problem.
I understand that there is some documentation in PyWin32.chm, and maybe other .CHM files, in the installed module. That's helpful. The readme.md should say this, and explain how to read those files.
Workarounds: Other projects have apparently taken on providing documentation for pywin32.
- ActiveState 3.4 and earlier has pywin32 documentation as HTML. When I change that URL to versions after 3.4, the document is not found.
- Tim Golden's HTML rendition of PyWin32.chm
- O'Reilly book, Python Programming On Win32. Dates from 2000. A StackOverflow contributor commented, "a great, if dated, book on the subject. I've read it and is very good." But it is 20 years old.
- StackOverflow question, Why can't I find any pywin32 documentation/resources. Dates from 2011. Features the comment, "The pywin32 project is such a tragedy. So much potential being wasted due to poor deployment. [Tim Golden's HTML Rendition] is just an ugly mess."
- StackOverflow question, python win32 extensions documentation. The StackOverflow people closed this question for being off-topic. I suspect what they meant by that is that pywin32 should document pywin32, and not leave it to StackOverflow.
If the pywin32 project wants to rely on external documentation like these, that is OK, but it should link to them in a discoverable way.
Would a patch adding some of this information to readme.md be welcomed by the maintainers? I don't have Windows, so there's a limit to how well I can describe PyWin32.chm. I can, however, add a section to the readme.
(It's worth keeping in mind that README.md isn't installed - so changes there are going to help people landing here on github, but not help people once it's installed. The .chm has a shortcut added when the .exe installers are used, so it's relatively obvious to users once it has been installed.
@mhammond I know sphinx pretty well (which can be used to produce HTML, CHM, and many other help formats) and would be happy to help move the current docs over to sphinx. If you could provide a little primer on how to build the current help, where the files are located, etc. that would be a great starting point!
Great, thanks!
https://github.com/mhammond/pywin32/tree/master/AutoDuck is where all the magic happens. The biggest issue is likely to be the format of the markup used in the source files (eg, look for things like @pymethod in almost any .cpp file in the repo)
It's worth keeping in mind that README.md isn't installed - so changes there are going to help people landing here on github, but not help people once it's installed.
Would you be open to a PR which added the README to the package? PyPI supports markdown now, so the same document could also be used as the overview on PyPI.
Whilst first-party docs can (and should) definitely be improved, in the interim typeshed does an awesome job at listing top-level modules, packages and aliases:
- Source: https://github.com/python/typeshed/tree/main/stubs/pywin32
- Using the stubs for IntelliSense and type-checking: https://pypi.org/project/types-pywin32/
Relates to #1992
