Repository navigation
Enhancement to read XML doc strings from .NET libraries instead of just signature. #374
Description
Environment
- Pythonnet version: 2.2.2
- Python version: 2.7.13 x86
- Operating System: Win10x64
Details
Various IDE's and Consoles (VS2015 with PTVS, Jupyter Notebook, ipython console etc) will show the function signature or class description within a .NET assembly for Intellisense/Autocompletion etc, but only the types are retrieved. I believe pythonnet pulls this info from the [class | function].doc field, as this is what shows up in the console/IDE for autocompletion.
Ex:
import clr
clr.AddReference("System")
import System
import System.Text
print System.Text.StringBuilder.__doc__Void .ctor()
Void .ctor(Int32)
Void .ctor(Int32, Int32)
Void .ctor(System.String)
Void .ctor(System.String, Int32)
Void .ctor(System.String, Int32, Int32, Int32)
It would be useful to be able to get more of what IronPython does, where it pulls the documentation for .NET libraries from the XML header (instead of the python docstring), which has much more detail on the parameters and saves you from looking up every class or function to get these details.
Ex:
import clr
clr.AddReference("System")
import System
import System.Text
print System.Text.StringBuilder.__doc__Represents a mutable string of characters. This class cannot be inherited.
StringBuilder()
StringBuilder(capacity: int)
StringBuilder(value: str)
StringBuilder(value: str, capacity: int)
StringBuilder(value: str, startIndex: int, length: int, capacity: int)
StringBuilder(capacity: int, maxCapacity: int)
Reacted by NValerij, Nils Hjelte, E+E AppDev and Chris Anderson
Activity
vmuriart commentedon Feb 10, 2017
This doesn't look to be possible.
http://stackoverflow.com/questions/28495651/how-to-get-documentation-of-method-or-class-using-reflection
filmor commentedon Feb 12, 2017
It's not entirely impossible. If the DLL is accompanied by an XML file one can get the XML doc comments from that one, e.g. http://jolt.codeplex.com/wikipage?title=Jolt.XmlDocComments&referringTitle=Jolt
vmuriart commentedon Feb 13, 2017
Out of curiosity, is the
.xmlnormally included as part of distributions? Is there one forSystem? Personally in my domain, I never gotten an.xmlalong with the binary, though in all fairness I also get alot of code without any comments.I like the idea of using the
.xmlif we can find it (ie,try-catch) but looks likejolthasn't been updated in a while. We could implement our own version of it, or see if can get the.netdevelopers to add built-in support for it on the newer frameworks.den-run-ai commentedon Feb 13, 2017
lcorrigan commentedon Feb 14, 2017
Although it would be nice to have this feature for all .NET libraries, if it were limited to those assemblies that have accompanying XML help files it would be an awesome start. Our in-house libraries (large set) are created with Sandcastle XML documentation for a chm file already, so if pythonnet was able to read them for intellisense/autocompletion it would be great for rapid scripting. I appreciate the work you guys are doing on this.
vmuriart commentedon Feb 14, 2017
@lcorrigan which IDE are you using? Most IDE's I've used with
pythonnethave issues providing code completion for.netlibraries. I thinkspyderandjupyter notebookare able to provide some code completion after you've run the import code.For
pycharmI think we need to generate code skeletons so that it provides auto completion. Other IDE's i think use Jedi Autocomplete, so we may need to find a way to hook into those.vmuriart commentedon Feb 14, 2017
Note, my previous comment is a related issue but shouldn't be a requirement to get this issue closed.
lcorrigan commentedon Feb 14, 2017
@vmuriart I mostly use PTVS for Visual Studio 2015. This is the IDE I used to create my initial post. In-house we use IronPython with this due to the high number of in-house .NET code we have (some folks use Eclipse with PyDev). I most recently started using Jupyter with CPython for some number crunching and plotting (I love it) but IronPython is not fully welcome in matplotlib, numpy and pandas world. We do a lot of prototyping and semi-automation so the ability to keep our eyes out of the help files and on the python script is really helpful (every day is different).
My end goal / cadillac use-case since about 2004 has been to have a windows environment running CPython exclusively (not IronPython) with:
There have been many improvements to the libraries and IDE's over the years but still haven't managed to cobble that one-stop-shopping CPython-based solution together that uses only mainstream libraries and tools without hacks.
Maybe it's just a pipe dream but seems to be more listeners than in 2004, so maybe one day....
vmuriart commentedon Feb 14, 2017
@lcorrigan actually you just brought up a really good point; if
IronPythonhas already implemented this we can review their implementation to see if we can mimic it.IronPythonhas a tighter integration to Visual Studio since its supported by Microsoft, but it wouldn't hurt to peak over the fence and see what they have.Sounds like you have some experience with setting up
PTVSfor unittests, do you have a public example we can check out? I haven't seen many examples of projects usingptvsso I been staying away from it.lcorrigan commentedon Feb 14, 2017
@vmuriart I've attached a very, very stripped-down VS2015 solution that follows our common test code format for unittest with IronPython. It's not runnable - it just shows the structure, as I couldn't send the real-deal. We have a class that inherits from unittest but adds some extra stuff for us where we found 'unittest', 'nose' and 'logging' were missing for our special logging and reporting needs. Some of this is still sprinkled in there as I needed to leave something.
The PTVS team has made a lot of traction in the last while - I can honestly say I love using it. It even allows me to have a CPython project and an IronPython project in the same solution each with their own interpreter console (though this is exactly what I'm trying to avoid). I usually create Sequencer files for test suites as I have not gotten along with the VS Test Explorer window. We usually use decorators on our test case functions (which tie into our test case tracking system) and the tests are not found when those are there, plus some other reasons I can't remember now. I've found Eclipse/Pydev better for that but I avoid that tool when I can. As mentioned, my goal is CPython + Jupyter for playing/prototyping and then push to VS2015 PTVS as a formal unittest for regression suites so I don't care about that test discovery tool as much. We are exploring Jenkins for some of that anyway. Hope this helps. Looking forward to seeing if you guys can build my Cadillac :)
ExamplePTVSUnitTest.zip
vmuriart commentedon Feb 14, 2017
@lcorrigan thanks for the example! Do you normally set a
StartupFileto run withf5?wrt the Cadillac, don't forget we accept
pull requests😄 .lcorrigan commentedon Feb 15, 2017
@vmuriart yes, I sometimes select a sequence file as the StartupFile and press Run/F5. But since I often keep a number of different sequencer files in a project, I most often just right-click on the sequence file in the editor and select 'Run without debugging'. That runs it directly in it's own iron python interpreter session. With that method, you can kick off multiple sequencer files (so long as they don't fight for the same resources) or keep playing in the main ipython console of the IDE. That's why I rename the console window titles at runtime (so I can tell which one is which).
Maybe about time I looked under the hood at the code of the tools I've been using - but I'm a long way from a pull request. Still worth a shot. Cheers.
vmuriart commentedon Feb 15, 2017
@denfromufa I just took a look at
SHFBand I don't think its what we are looking for. Looks likeSHFBis for generating documentation rather than parsing existing documentation.vmuriart commentedon Feb 24, 2017
Related Info & Summary:
Name.dllandName.xmldo seem to be somewhat of a standard and also to include them with the distribution of libraries (exampleNUnit)Standard Library (ex.
System) have xml docs as well (%ProgramFiles%\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0)Attribute documentation may be tricky
It can be accomplished without needing to depend on a 3rd party library as seen from IronPython's implementation on IronPython27 and IronPython3
The pythonnet code that would need to be updated is in class manager
den-run-ai commentedon Feb 24, 2017
@vmuriart can you summarize your findings from these links?
vmuriart commentedon Feb 24, 2017
@denfromufa updated my comment with the summary info. In conclusion, its doable and may be easier than I originally though. My previous comment lays out all the information needed to implement.
I tried looking if
Jythonhad a similar implementation but couldn't find anything in the 2 minutes i looked.den-run-ai commentedon Jul 14, 2017
Here is how to generate skeletons for Python.NET:
https://github.com/JetBrains/intellij-community/blob/dfc22bddce34c09fccdc9b616053b7996c1bd331/python/helpers/generator3.py
lostmsu commentedon Jul 11, 2022
If we decide to implement this, I'd love to reuse IronPython code directly.
Another example code here but I like the IronPython's one better.