Re: [python-win32] pywin32 Documentation
Vernon.The fantastic work is all yours. I simply started converting your quick_reference.md to reStructuredText.-BrianOn Dec 6, 2022, at 7:52 AM, Vernon D. Cole wrote:Brian:I did not see your entry before writing mine. Fantastic work on the adodbapi calling interfaces! I think that there is still a need for something like the quick_reference, so that there can be discussion about things like the extensions. The ability to switch between paramstyles is probably still unique. There was discussion in the dbapi community that it was impossible to do. Sometimes that sort of thing is best presented in paragraph format.I still have the original source for Python Programming on Win32 (thank you, Mark) but O'Reilly was not interested in publishing a second edition several years ago. Perhaps it is time to ask them again.On Tue, Dec 6, 2022 at 3:02 AM Brian Johnson wrote:Hi Mark.Thank you for the feedback. My responses in-line below. Also...Example of reformatted narrative doc:Quick Start to Client side COM and Python — pywin32 305 documentation (brian3johnson.github.io)Example of api docs generated from .py docstring:adodbapi package — pywin32 305 documentation (brian3johnson.github.io)Note: the TOC sidebar still needs work.Thanks for your interest. I probably should have written more about this earlier. From my POV, the main considerations I have are:1) Much of the documentation is inside the c++ source formatted via "autoduck" style comments. I really don't want to abandon this documentation, but I don't think it's helpful in a sphinx-based world?BJ > I would not want to abandon this either. I don't know much about Autoduck apart from gathering that it generates documentation from the C++ source. There may be an approach using SWIG with some modifications within the C++ source code:https://www.swig.org/Doc4.1/Python.html#Python_nn65 2) There's no where near as much docs embedded in the .py code, which is something that we can address. However, some work has started on https://github.com/mhammond/pywin32/issues/1913, which hopes to add type annotations - see also yesterday's mail to this list on this topic. While I'm not quite sure exactly what approach is being suggested for that, it seems possible it will have at least *some* overlap here?BJ > Yes, I saw the email about this yesterday. Good news is that those type hints/annotations can be used by sphinx to generate the api docs. In fact, this is something I would have done as part of this documentation effort.3) Working out a good layout in the repo for docs is also important, but I don't forsee any real obstacles here - as you mention, a TOC etc are important. .rst seems like a perfectly reasonable format for hand-written docs, and given there aren't really that many hand-written docs in the tree which remain relevant, hand-converting them to largely unformatted markdown seems reasonable in the first instance. There's always going to be a bit of tension between keeping the docs organized and trying to keep the docs fairly close to the implementation they are documenting, but we can manage that.BJ> Agreed.4) I'd want to kill the existing tooling entirely as it's just going stale. Eg, the way https://mhammond.github.io/pywin32/ is built is interesting (it decompiles the .chm!) but that seems like a dead-end - I suspect that at some point it will end up extremely difficult to build that .chm in the first place - finding the Windows HTML Help compiler today is difficult enough.BJ> I agree with this as well. In fact, sphinx can generate HTMLHelp for compiling to CHM if you still want to have a CHM file available.So really, the big unknowns for me that need answering are:* How exactly do the autoduck comments get handled as they change?BJ> Maybe via SWIG. More research needed.* How does adding docs to the .py files overlap with adding type hints?BJ> Overlaps perfectly.* Does it replace the existing system rather than adding yet more complexity to it?BJ> ReplacesI'll look a little more at your repo over the next week or so, but I'm currently a bit short on time, but really am interested in improving the docs, so thanks!BJ> Sounds good! Thanks!___ python-win32 mailing list python-win32@python.org https://mail.python.org/mailman/listinfo/python-win32___ python-win32 mailing list python-win32@python.org https://mail.python.org/mailman/listinfo/python-win32
Re: [python-win32] pywin32 Documentation
Hi Vernon. I made an initial pass with moving it.Python ADODBAPI quick reference — pywin32 305 documentationbrian3johnson.github.ioI have mot worked through cleaning up the format nor scrubbing it for old code or dead links. Thanks!BrianOn Dec 6, 2022, at 7:33 AM, Vernon D. Cole wrote:The most important document for adodbapi is in Markdown. (That's an improvement - - I wrote it in .odt) so if that helps the decision, I would say lean toward that direction.It needs to be linked / indexed in where people can actually find it. adodbapi/quick_reference.md If we make an actual .docs directory, it should move there.It also needs an edit pass to get rid of obsolete references to Python 2 and to check that the external links still work and so forth. I'll add that to my to-do list.On Mon, Dec 5, 2022 at 6:57 PM Brian Johnson <br...@brian3johnson.me> wrote:Hi.I took a stab at upgrading and "untangling" the documentation. I am willing to work on this documentation "untangling" project. Before I put more effort into it, I would like to get feedback from Mark and other contributors on what I'm proposing. If so, I'll log an Issue and/or pull request.Motivation: I need to work with a COM server application and want to use python. I found it challenging to find documentation and examples. Also, Mark mentioned this in the repo README: "Lots of that is very old, but some is auto-generated and current. Would love help untangling the docs!"Where: The current iteration is hosted on my forked repo at Python for Windows Extensions — pywin32 305 documentation (brian3johnson.github.io). If this effort moves forward, I'll pull it down once it's built and posted from mhammond's repo.How: I am building the documentation with sphinx Welcome — Sphinx documentation (sphinx-doc.org) to update the narrative docs and automate or semi-automate the pywin32 API reference. I am using the default theme. I'm using reStructuredText (.rst) for the docs.What: I included all the existing narrative documentation from the CHM. Most of it remains unformatted, except for a couple of docs. I added a Home page, Installation, Support, and Resources pages, and the start of a Getting Started Tutorial.Proposed Next Steps:1. Confirm if I move forward with sphinx. If so, confirm if we use reStructuredText (reStructuredText — Sphinx documentation (sphinx-doc.org)) or Markdown (Markdown — Sphinx documentation (sphinx-doc.org)) for narrative documents.2. Finish formatting the existing narrative docs per rst or md.3. Add docstrings to .py source files to generate API docs.4. Convert some of the "samples" embedded in the source files to "How-tos".I have more ideas and suggestions, which I can share in an Issue, PR, or on this mailing list.I look forward to hearing what you think.Sincerely,Brian___ python-win32 mailing list python-win32@python.org https://mail.python.org/mailman/listinfo/python-win32 ___ python-win32 mailing list python-win32@python.org https://mail.python.org/mailman/listinfo/python-win32
Re: [python-win32] pywin32 Documentation
Hi Mark.Thank you for the feedback. My responses in-line below. Also...Example of reformatted narrative doc:Quick Start to Client side COM and Python — pywin32 305 documentation (brian3johnson.github.io)Example of api docs generated from .py docstring:adodbapi package — pywin32 305 documentation (brian3johnson.github.io)Note: the TOC sidebar still needs work. Thanks for your interest. I probably should have written more about this earlier. From my POV, the main considerations I have are:1) Much of the documentation is inside the c++ source formatted via "autoduck" style comments. I really don't want to abandon this documentation, but I don't think it's helpful in a sphinx-based world?BJ > I would not want to abandon this either. I don't know much about Autoduck apart from gathering that it generates documentation from the C++ source. There may be an approach using SWIG with some modifications within the C++ source code:https://www.swig.org/Doc4.1/Python.html#Python_nn65 2) There's no where near as much docs embedded in the .py code, which is something that we can address. However, some work has started on https://github.com/mhammond/pywin32/issues/1913, which hopes to add type annotations - see also yesterday's mail to this list on this topic. While I'm not quite sure exactly what approach is being suggested for that, it seems possible it will have at least *some* overlap here?BJ > Yes, I saw the email about this yesterday. Good news is that those type hints/annotations can be used by sphinx to generate the api docs. In fact, this is something I would have done as part of this documentation effort.3) Working out a good layout in the repo for docs is also important, but I don't forsee any real obstacles here - as you mention, a TOC etc are important. .rst seems like a perfectly reasonable format for hand-written docs, and given there aren't really that many hand-written docs in the tree which remain relevant, hand-converting them to largely unformatted markdown seems reasonable in the first instance. There's always going to be a bit of tension between keeping the docs organized and trying to keep the docs fairly close to the implementation they are documenting, but we can manage that.BJ> Agreed.4) I'd want to kill the existing tooling entirely as it's just going stale. Eg, the way https://mhammond.github.io/pywin32/ is built is interesting (it decompiles the .chm!) but that seems like a dead-end - I suspect that at some point it will end up extremely difficult to build that .chm in the first place - finding the Windows HTML Help compiler today is difficult enough.BJ> I agree with this as well. In fact, sphinx can generate HTMLHelp for compiling to CHM if you still want to have a CHM file available.So really, the big unknowns for me that need answering are:* How exactly do the autoduck comments get handled as they change?BJ> Maybe via SWIG. More research needed.* How does adding docs to the .py files overlap with adding type hints?BJ> Overlaps perfectly.* Does it replace the existing system rather than adding yet more complexity to it?BJ> ReplacesI'll look a little more at your repo over the next week or so, but I'm currently a bit short on time, but really am interested in improving the docs, so thanks!BJ> Sounds good! Thanks!___ python-win32 mailing list python-win32@python.org https://mail.python.org/mailman/listinfo/python-win32
[python-win32] pywin32 Documentation
Hi.I took a stab at upgrading and "untangling" the documentation. I am willing to work on this documentation "untangling" project. Before I put more effort into it, I would like to get feedback from Mark and other contributors on what I'm proposing. If so, I'll log an Issue and/or pull request.Motivation: I need to work with a COM server application and want to use python. I found it challenging to find documentation and examples. Also, Mark mentioned this in the repo README: "Lots of that is very old, but some is auto-generated and current. Would love help untangling the docs!"Where: The current iteration is hosted on my forked repo at Python for Windows Extensions — pywin32 305 documentation (brian3johnson.github.io). If this effort moves forward, I'll pull it down once it's built and posted from mhammond's repo.How: I am building the documentation with sphinx Welcome — Sphinx documentation (sphinx-doc.org) to update the narrative docs and automate or semi-automate the pywin32 API reference. I am using the default theme. I'm using reStructuredText (.rst) for the docs.What: I included all the existing narrative documentation from the CHM. Most of it remains unformatted, except for a couple of docs. I added a Home page, Installation, Support, and Resources pages, and the start of a Getting Started Tutorial.Proposed Next Steps:1. Confirm if I move forward with sphinx. If so, confirm if we use reStructuredText (reStructuredText — Sphinx documentation (sphinx-doc.org)) or Markdown (Markdown — Sphinx documentation (sphinx-doc.org)) for narrative documents.2. Finish formatting the existing narrative docs per rst or md.3. Add docstrings to .py source files to generate API docs.4. Convert some of the "samples" embedded in the source files to "How-tos".I have more ideas and suggestions, which I can share in an Issue, PR, or on this mailing list.I look forward to hearing what you think.Sincerely,Brian___ python-win32 mailing list python-win32@python.org https://mail.python.org/mailman/listinfo/python-win32
Re: [python-win32] Welcome to the "python-win32" mailing list (Digest mode)
Hi python-win32 community.I am trying to get this toy COM server (code is below) to work. It is the sample code from "Python Programming for Win32" and adapted for python 3.10. When I test it using VBA in Word, I get this error:Run-time error '429':ActiveX component can't create objectI don't know if I am missing one a
required _reg_param_ that is needed for Win10.Is there is an extra step I need to take to register/run the COM server?I don't know if win32com.server.localserver.serve [] is necessary.Does the class need an __init__ method to do something?I appreciate any help or insight into getting this to work. Thank you!Sincerely,
BrianContext:Windows 10, python 3.10, Office 365, running python code as AdministratorI have verified the python class works in python only.I tried registering/unregistering using both options shown below. Both appear to work - no error messages. I can find info about the COM Server using Regedit.I tried the --debug flag, but it
didn't provide any verbosity.I'm learning COM, but the info about it is sparse and generally very abstract.Python script, SimpleCOMServer.py:"""A sample COM server - almost as small as they come."""# import sysimport pythoncomimport win32com.server.registerclass PythonUtilities:
"""We expose a simple method in a Python COM object.""" _reg_clsctx_ = pythoncom.CLSCTX_LOCAL_SERVER _public_methods_ = ["SplitString"] _reg_progid_ = "PythonDemos.Utilities" _reg_desc_ = "PythonDemos Test COM Server" # NEVER copy the following ID # Use
"print(pythoncom.CreateGUID())" to made a new on. _reg_clsid_ = "{819E8336-00B5-4025-979A-46EE1EF411B7}" # for Python 3.7+ # https://stackoverflow.com/questions/1054849/consuming-python-com-server-from-net _reg_verprogid_ = "PythonDemos.Utilities.1" # .
_reg_class_spec_ = "SimpleCOMServer.PythonUtilities" def SplitString(self, val, separator=None): """Split a string by a separator.""" # if separator is not None: # return val.split(separator) # else: # return val.split() if separator
is not None: return str(val).split(str(separator)) else: return str(val).split()# Add code so that when this script is run by python e.e, it self-registers.if __name__ == "__main__": print("Registering COM server...") win32com.server.register.UseCommandLine(PythonUtilities)
# if "--register" in sys.argv[1:] or "--unregister" in sys.argv[1:]: # win32com.server.register.UseCommandLine(PythonUtilities) # else: # # start the server. # from win32com.server.localserver import serve # serve(["{819E8336-00B5-4025-979A-46EE1EF411B7}"])Word VBA
macro:Sub TestPython() Dim PythonUtils As Object Set PythonUtils = CreateObject("PythonDemos.Utilities") response = PythonUtils.SplitString("Hello from VB") For Each Item In response MsgBox Item NextEnd Sub___
python-win32 mailing list
python-win32@python.org
https://mail.python.org/mailman/listinfo/python-win32
