python / python/mypy

Stubgen user documentation of modules

Open
#14,094 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug topic-stubgen
Dominant language
Python
Stars
20.6k
Forks
3.3k
PR merge metrics
PR metrics pending

Description

I have a boost compiled module pyClass if i import the class and check the documentation of the class using the help function:

>>> import pyClass
>>> help(pyClass)
Help on module pyClass:

NAME
    pyClass

CLASSES
    Boost.Python.instance(builtins.object)
        MyClass

    class MyClass(Boost.Python.instance)
     |  Method resolution order:
     |      MyClass
     |      Boost.Python.instance
     |      builtins.object
     |
     |  Static methods defined here:
     |
     |  __init__(...)
     |      __init__( (object)arg1, (str)arg2) -> None :
     |
     |          C++ signature :
     |              void __init__(struct _object * __ptr64,class std::basic_string<char,struct std::char_traits<char>,class std::allocator<char> >)
     |
     |  __reduce__ = <unnamed Boost.Python function>(...)
     |
     |  __repr__(...)
     |      __repr__( (MyClass)arg1) -> str :
     |
     |          C++ signature :
     |              class std::basic_string<char,struct std::char_traits<char>,class std::allocator<char> > __repr__(class MyClass)
     |
     |  foo(...)
     |      foo( (MyClass)arg1, (int)a [, (str)b [, (int)c [, (float)d]]]) -> int :
     |          f's docstring
     |
     |          C++ signature :
     |              int foo(class MyClass {lvalue},int [,char [,unsigned int [,double]]])
     |
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |
     |  name
     |
     |  number
     |
     |  valueReadOnly
     |
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |
     |  __instance_size__ = 80
     |
     |  ----------------------------------------------------------------------
     |  Static methods inherited from Boost.Python.instance:
     |
     |  __new__(*args, **kwargs) from Boost.Python.class
     |      Create and return a new object.  See help(type) for accurate signature.
     |
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from Boost.Python.instance:
     |
     |  __dict__
     |
     |  __weakref__

FILE
    d:\documents\development\cpp\pythonclib\install\lib\python\cpppythonlib\pyclass.pyd

All the type information is in the module like function parameters and doc strings.

If i run stubgen -p pyClass the resulting file pyClass.pyi doesn't contain any of this information

from typing import Any, ClassVar

import Boost.Python

class MyClass(Boost.Python.instance):
    __instance_size__: ClassVar[int] = ...
    name: Any
    number: Any
    @classmethod
    def __init__(cls, *args, **kwargs) -> None: ...
    @classmethod
    def foo(cls, *args, **kwargs) -> Any: ...
    @classmethod
    def __reduce__(cls) -> Any: ...
    @property
    def valueReadOnly(self) -> Any: ...

Is this information not parsed by stubgen?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the Boost.Python module example and running stubgen -p pyClass, then compare the generated pyClass.pyi with the output from help(pyClass). Trace how stubgen handles compiled modules and determine whether signatures, docstrings, and type information can be retained; done means the generated stub reflects the available module documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.