-
Type:
Bug
-
Status: Closed
-
Priority:
Minor - P4
-
Resolution: Duplicate
-
Affects Version/s: 2.0
-
Fix Version/s: None
-
Component/s: asyncio
-
Labels:None
Currently, we shorten/obfuscate the module name when dynamically generating our framework-specific public API classes. E.g. when we create AsyncIOMotorClient we do:
def create_asyncio_class(cls): |
return create_class_with_framework(cls, asyncio_framework, 'motor_asyncio') |
|
AsyncIOMotorClient = create_asyncio_class(core.AgnosticClient) |
with the factory function defined as:
def create_class_with_framework(cls, framework, module_name): |
motor_class_name = framework.CLASS_PREFIX + cls.__motor_class_name__ |
cache_key = (cls, motor_class_name, framework) |
cached_class = _class_cache.get(cache_key) |
if cached_class: |
return cached_class |
|
new_class = type(str(motor_class_name), cls.__bases__, cls.__dict__.copy()) |
new_class.__module__ = module_name |
new_class._framework = framework |
...
|
...
|
Consequently, AsyncIOMotorClient appears to belong (as per its _module_ value) to the motor_asyncio module, even though it actually resides in motor.motor_asyncio. This creates problems when we attempt to use intersphinx to link to the MOTOR documentation as seen in MOTOR-338.
Unless there is a good rationale for fudging the _module_ of these classes, we should change the code so that it reflects the actual path.
ORIGINAL DESCRIPTION
In my conf.py I have:
extensions = [
|
'sphinx.ext.autodoc',
|
'sphinx.ext.autosummary',
|
'sphinx.ext.intersphinx',
|
'sphinx.ext.extlinks',
|
]
|
|
intersphinx_mapping = {
|
'python': ('https://docs.python.org/3/', None),
|
'motor': ('https://motor.readthedocs.io/en/stable/', None),
|
}
|
code.rst:
.. automodule:: code
|
:members:
|
:undoc-members:
|
:show-inheritance:
|
code.py:
from asyncio.motor_asyncio import ( AsyncIOMotorClient, AsyncIOMotorDatabase, AsyncIOMotorCollection)
|
|
class MyClient(AsyncIOMotorClient):
|
pass
|
|
class MyDatabase(AsyncIOMotorDatabase):
|
pass
|
|
class MyCollection(AsyncIOMotorCollection):
|
pass
|
Sphinx output:
code.py:docstring of code.MyClient:1: WARNING: py:class reference target not found: motor_asyncio.AsyncIOMotorClient
code.py:docstring of code.MyDatabase:1: WARNING: py:class reference target not found: motor_asyncio.AsyncIOMotorDatabase
code.py:docstring of code.MyCollection:1: WARNING: py:class reference target not found: motor_asyncio.AsyncIOMotorCollection
Adding a top-level module 'motor_asyncio' to the intersphinx configuration does not help.
References in the docstrings and .rst files to :class:`motor.motor_asyncio.AsyncIOMotorClient` work fine.
- is duplicated by
-
MOTOR-339 Don't obfuscate full module name when generating framework-specific API classes
-
- Closed
-