TypeVar objects not documenting as expected

[lamesjaidler]

Describe the bug

I'm wanting to document some modules in a package I'm developing. Throughout the modules I've imported some TypeVar objects from a module within the package - these objects refer to different types of data objects. I've done this mainly so that I can use Pandas and Koalas dataframes within a given module without having to import Pandas/Koalas just for the type hints.

When I run sphinx to document the modules, I expect the value assigned to the TypeVar object to be displayed. However, I get the module where the TypeVar object is stored, plus the value assigned to the TypeVar object.

How to Reproduce

Let's say I have the following package structure:

example_package
├── __init__.py
├── example_module
│   ├── __init__.py
│   └── example_module.py
└── typevar_objects
    ├── __init__.py
    └── typevar_objects.py

I keep my TypeVar objects in typevar_objects.py:

from typing import TypeVar

PandasDataFrameType = TypeVar('pandas.core.frame.DataFrame')

Then in my module example_module.py, I import the TypeVar object as shown:

from typevar_objects import PandasDataFrameType

class A:
    def some_func(self, df: PandasDataFrameType):
        return None

Using the following settings in conf.py:

import os
import sys
import example_package

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.imgmath',
    'sphinx.ext.autosummary',
]

autodoc_member_order = "bysource"
autodoc_default_options = {
    "members": True,
    'undoc-members': True,
    'member-order': 'bysource',
}
autodoc_typehints = 'signature'
templates_path = ['_templates']
language = 'en'
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
todo_include_todos = True
master_doc = 'index'
numpydoc_show_class_members = False
autosummary_generate = True
panels_add_bootstrap_css = False
html_use_index = False
html_domain_indices = False
html_static_path = ['_static']

I run sphinx on the package using the commands:

rm -r doc
sphinx-apidoc -F -M -d 1 --separate -o doc example_package
cp conf.py doc
cd doc
make clean
make html

Expected behavior

I would expect the documentation for A.some_func to show df: pandas.core.frame.DataFrame. However, it instead shows df: example_package.typevar_objects.pandas.core.frame.DataFrame:

Your project

https://drive.google.com/file/d/1ncM_aEovRiqsJGOVJyBRUbJgDMzJIPF9/view?usp=sharing

Screenshots

No response

OS

Mac

Python version

3.8.9

Sphinx version

4.3.1

Sphinx extensions

sphinx.ext.autodoc, sphinx.ext.viewcode, sphinx.ext.todo, sphinx.ext.imgmath, sphinx.ext.autosummary

Extra tools

No response

Additional context

No response

[tk0miya]

In PEP-484, the argument of TypeVar has been described as below:

The argument to TypeVar() must be a string equal to the variable name to which it is assigned. Type variables must not be redefined.
https://www.python.org/dev/peps/pep-0484/#generics

So I think PandasDataFrameType = TypeVar('pandas.core.frame.DataFrame') is not good usage. And it is not the same as pands.core.frame.DataFrame. So it will not be rendered as df: pandas.core.frame.DataFrame.

[lamesjaidler]

@tk0miya but even if I create a type var like PandasDataFrameType = TypeVar('PandasDataFrameType'), the documentation will still show the module where the TypeVar is stored (e.g. something like example_package.typevar_objects.typevar_objects.PandasDataFrameType. So is there a setting or something in the conf.py that I need to set for it to omit the imported module for TypeVar objects?

[tk0miya]

Sorry, I'm not sure what you'd like to do. What is the expected type of argument? If you'd like to take pandas.core.frame.DataFrame, you should use it directly instead of TypeVar.

[lamesjaidler]

I have a few modules that use Pandas syntax, but can also be used with Koalas. However, I don't want to import Pandas or Koalas as I have separate install requirements for Koalas and would like the user to be able to install either the Pandas-ready or Koalas-ready version. The module works fine without the imports, but to use type hints that directly reference Pandas/Koalas, I'd have to import them, which why I'm trying to use TypeVars instead. Hopefully I've made that relatively clear!

[tk0miya]

IMO, your usecase of TypeVar is wrong. It is not an alias of class. It's mainly used to represent a generic class. See https://docs.python.org/3/library/typing.html#user-defined-generic-types

For that purpose, please use typing.TYPE_CHECKING flag and string typehint instead.

[lamesjaidler]

I'll try this out, thanks!