Navigation Menu

Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Dataclass field types are not rendered when factories are used #10893

Open
DifferentialOrange opened this issue Oct 3, 2022 · 1 comment
Open

Dataclass field types are not rendered when factories are used #10893

DifferentialOrange opened this issue Oct 3, 2022 · 1 comment
Labels
extensions:autodoc type:bug
Milestone
7.x

Comments

@DifferentialOrange
Copy link

DifferentialOrange commented Oct 3, 2022 •
edited

Describe the bug

When @dataclass with optional fields and factories is defined, documentation generated with :automodule: displays plain text ~module.Class instead of clickable links in __init__ description.

The following code

source 

def QueueFactory():
    """
    Build a queue-based channel
    """
    return queue.Queue(maxsize=1)


@dataclass
class PoolUnit():
    """
    Class to store a Tarantool instance metainfo and
    to work with it as a part of connection pool.
    """

    addr: dict
    """
    ``{"host": host, "port": port}`` info

    :type: :obj:`dict`
    """

    conn: Connection
    """
    :type: :py:class:`~tarantool.Connection`
    """

    input_queue: queue.Queue = field(default_factory=QueueFactory)
    """
    Channel to pass requests for the instance thread

    :type: :obj:`queue.Queue`
    """

    output_queue: queue.Queue = field(default_factory=QueueFactory)
    """
    Channel to receive responses from the instance thread

    :type: :obj:`queue.Queue`
    """

    thread: typing.Optional[threading.Thread] = None
    """
    Background thread to process requests for the instance

    :type: :obj:`threading.Thread`
    """

    state: InstanceState = field(default_factory=InstanceState)
    """
    Current instance state

    :type: :py:class:`~tarantool.connection_pool.InstanceState`
    """

    request_processing_enabled: bool = False
    """
    Flag used to stop requests processing requests in background thread
    on connection close or destruction.

    :type: :obj:`bool`
    """

is compiled to (see screenshot)

HTML 

<dl class="py class">
<dt class="sig sig-object py" id="tarantool.connection_pool.PoolUnit">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarantool.connection_pool.</span></span><span class="sig-name descname"><span class="pre">PoolUnit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">addr:</span> <span class="pre">dict</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">conn:</span> <span class="pre">~tarantool.connection.Connection</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">input_queue:</span> <span class="pre">~queue.Queue</span> <span class="pre">=</span> <span class="pre">&lt;factory&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">output_queue:</span> <span class="pre">~queue.Queue</span> <span class="pre">=</span> <span class="pre">&lt;factory&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">thread:</span> <span class="pre">~typing.Optional[~threading.Thread]</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">state:</span> <span class="pre">~tarantool.connection_pool.InstanceState</span> <span class="pre">=</span> <span class="pre">&lt;factory&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">request_processing_enabled:</span> <span class="pre">bool</span> <span class="pre">=</span> <span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarantool.connection_pool.PoolUnit" title="Permalink to this definition"></a></dt>
<dd><p>Class to store a Tarantool instance metainfo and
to work with it as a part of connection pool.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="tarantool.connection_pool.PoolUnit.addr">
<span class="sig-name descname"><span class="pre">addr</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.10)"><span class="pre">dict</span></a></em><a class="headerlink" href="#tarantool.connection_pool.PoolUnit.addr" title="Permalink to this definition"></a></dt>
<dd><p><code class="docutils literal notranslate"><span class="pre">{&quot;host&quot;:</span> <span class="pre">host,</span> <span class="pre">&quot;port&quot;:</span> <span class="pre">port}</span></code> info</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.10)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">dict</span></code></a></p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="tarantool.connection_pool.PoolUnit.conn">
<span class="sig-name descname"><span class="pre">conn</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="module-connection.html#tarantool.connection.Connection" title="tarantool.connection.Connection"><span class="pre">Connection</span></a></em><a class="headerlink" href="#tarantool.connection_pool.PoolUnit.conn" title="Permalink to this definition"></a></dt>
<dd><dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference internal" href="module-tarantool.html#tarantool.Connection" title="tarantool.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a></p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="tarantool.connection_pool.PoolUnit.input_queue">
<span class="sig-name descname"><span class="pre">input_queue</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/queue.html#queue.Queue" title="(in Python v3.10)"><span class="pre">Queue</span></a></em><a class="headerlink" href="#tarantool.connection_pool.PoolUnit.input_queue" title="Permalink to this definition"></a></dt>
<dd><p>Channel to pass requests for the instance thread</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/queue.html#queue.Queue" title="(in Python v3.10)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">queue.Queue</span></code></a></p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="tarantool.connection_pool.PoolUnit.output_queue">
<span class="sig-name descname"><span class="pre">output_queue</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/queue.html#queue.Queue" title="(in Python v3.10)"><span class="pre">Queue</span></a></em><a class="headerlink" href="#tarantool.connection_pool.PoolUnit.output_queue" title="Permalink to this definition"></a></dt>
<dd><p>Channel to receive responses from the instance thread</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/queue.html#queue.Queue" title="(in Python v3.10)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">queue.Queue</span></code></a></p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="tarantool.connection_pool.PoolUnit.request_processing_enabled">
<span class="sig-name descname"><span class="pre">request_processing_enabled</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.10)"><span class="pre">bool</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">False</span></em><a class="headerlink" href="#tarantool.connection_pool.PoolUnit.request_processing_enabled" title="Permalink to this definition"></a></dt>
<dd><p>Flag used to stop requests processing requests in background thread
on connection close or destruction.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.10)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">bool</span></code></a></p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="tarantool.connection_pool.PoolUnit.state">
<span class="sig-name descname"><span class="pre">state</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="#tarantool.connection_pool.InstanceState" title="tarantool.connection_pool.InstanceState"><span class="pre">InstanceState</span></a></em><a class="headerlink" href="#tarantool.connection_pool.PoolUnit.state" title="Permalink to this definition"></a></dt>
<dd><p>Current instance state</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference internal" href="#tarantool.connection_pool.InstanceState" title="tarantool.connection_pool.InstanceState"><code class="xref py py-class docutils literal notranslate"><span class="pre">InstanceState</span></code></a></p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="tarantool.connection_pool.PoolUnit.thread">
<span class="sig-name descname"><span class="pre">thread</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Optional" title="(in Python v3.10)"><span class="pre">Optional</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/threading.html#threading.Thread" title="(in Python v3.10)"><span class="pre">Thread</span></a><span class="p"><span class="pre">]</span></span></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#tarantool.connection_pool.PoolUnit.thread" title="Permalink to this definition"></a></dt>
<dd><p>Background thread to process requests for the instance</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/threading.html#threading.Thread" title="(in Python v3.10)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">threading.Thread</span></code></a></p>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="tarantool.connection_pool.QueueFactory">
<span class="sig-prename descclassname"><span class="pre">tarantool.connection_pool.</span></span><span class="sig-name descname"><span class="pre">QueueFactory</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarantool.connection_pool.QueueFactory" title="Permalink to this definition"></a></dt>
<dd><p>Build a queue-based channel</p>
</dd></dl>

How to Reproduce

$ git clone git@github.com:tarantool/tarantool-python.git
$ cd ./tarantool-python/
$ git checkout git checkout 708902e175cfd5fcf9a992a2496c5c2fc0e6b795
$ pip install -r requirements.txt
$ pip install -r docs/requirements.txt
$ make docs
$ python -m http.server --directory build/sphinx/html
$ # open http://localhost:8000/api/submodule-connection-pool.html#tarantool.connection_pool.PoolUnit

Expected behavior

Clickable links in dataclass __init__, like in other dataclasses in the module

Your project

tarantool/tarantool-python@708902e

Screenshots

image

OS

Ubuntu 22.04

Python version

3.10.6

Sphinx version

5.2.1

Sphinx extensions

'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', 'sphinx_paramlinks'

Extra tools

No response

Additional context

No response
@DifferentialOrange DifferentialOrange mentioned this issue Oct 3, 2022
Closed
@AA-Turner AA-Turner modified the milestones: 5.x, 6.x, 5.3.0 Oct 4, 2022
DifferentialOrange added a commit to tarantool/tarantool-python that referenced this issue Oct 10, 2022
@DifferentialOrange
doc: describe tarantool submodules API
0d15096 
Add or update docstings for submodule files contents. Submodules are not
meant to be used directly in code, but their descriptions will be
imported automatically to core module API description. It also may
help developers of this module.

Every submodule that could be of use is indexed in documentation now.

Set sphinx autodoc module to describe members and inherited members by
default.

Dataclass with factories display is not parsed correctly, see [1] issue.

1. sphinx-doc/sphinx#10893

Part of #67
DifferentialOrange added a commit to tarantool/tarantool-python that referenced this issue Oct 10, 2022
@DifferentialOrange
doc: describe tarantool submodules API
0b23068 
Add or update docstings for submodule files contents. Submodules are not
meant to be used directly in code, but their descriptions will be
imported automatically to core module API description. It also may
help developers of this module.

Every submodule that could be of use is indexed in documentation now.

Set sphinx autodoc module to describe members and inherited members by
default.

Dataclass with factories display is not parsed correctly, see [1] issue.

1. sphinx-doc/sphinx#10893

Part of #67
DifferentialOrange added a commit to tarantool/tarantool-python that referenced this issue Oct 10, 2022
@DifferentialOrange
doc: describe tarantool submodules API
f10a060 
Add or update docstings for submodule files contents. Submodules are not
meant to be used directly in code, but their descriptions will be
imported automatically to core module API description. It also may
help developers of this module.

Every submodule that could be of use is indexed in documentation now.

Set sphinx autodoc module to describe members and inherited members by
default.

Dataclass with factories display is not parsed correctly, see [1] issue.

1. sphinx-doc/sphinx#10893

Part of #67
DifferentialOrange added a commit to tarantool/tarantool-python that referenced this issue Oct 10, 2022
@DifferentialOrange
doc: describe tarantool submodules API
73bfb6e 
Add or update docstings for submodule files contents. Submodules are not
meant to be used directly in code, but their descriptions will be
imported automatically to core module API description. It also may
help developers of this module.

Every submodule that could be of use is indexed in documentation now.

Set sphinx autodoc module to describe members and inherited members by
default.

Dataclass with factories display is not parsed correctly, see [1] issue.

1. sphinx-doc/sphinx#10893

Part of #67
DifferentialOrange added a commit to tarantool/tarantool-python that referenced this issue Oct 10, 2022
@DifferentialOrange
doc: describe tarantool submodules API
f7bb997 
Add or update docstings for submodule files contents. Submodules are not
meant to be used directly in code, but their descriptions will be
imported automatically to core module API description. It also may
help developers of this module.

Every submodule that could be of use is indexed in documentation now.

Set sphinx autodoc module to describe members and inherited members by
default.

Dataclass with factories display is not parsed correctly, see [1] issue.

1. sphinx-doc/sphinx#10893

Part of #67
DifferentialOrange added a commit to tarantool/tarantool-python that referenced this issue Oct 10, 2022
@DifferentialOrange
doc: describe tarantool submodules API
22b1eb1 
Add or update docstings for submodule files contents. Submodules are not
meant to be used directly in code, but their descriptions will be
imported automatically to core module API description. It also may
help developers of this module.

Every submodule that could be of use is indexed in documentation now.

Set sphinx autodoc module to describe members and inherited members by
default.

Dataclass with factories display is not parsed correctly, see [1] issue.

1. sphinx-doc/sphinx#10893

Part of #67
DifferentialOrange added a commit to tarantool/tarantool-python that referenced this issue Oct 11, 2022
@DifferentialOrange
doc: describe tarantool submodules API
4f5ca93 
Add or update docstings for submodule files contents. Submodules are not
meant to be used directly in code, but their descriptions will be
imported automatically to core module API description. It also may
help developers of this module.

Every submodule that could be of use is indexed in documentation now.

Set sphinx autodoc module to describe members and inherited members by
default.

Dataclass with factories display is not parsed correctly, see [1] issue.

1. sphinx-doc/sphinx#10893

Part of #67
@AA-Turner AA-Turner modified the milestones: 5.3.0, 6.x Oct 15, 2022
@timmysilv timmysilv mentioned this issue Jan 11, 2023
Merged
@4flixt 4flixt mentioned this issue Apr 26, 2023
Open
@AA-Turner AA-Turner modified the milestones: 6.x, 7.x Apr 29, 2023
@snorkysnark
Copy link

Since the culprit is the string <factory>, for now you can replace it with a different placeholder: for example, using a small extension

from dataclasses import is_dataclass

def process_signature(app, what, name, obj, options, signature, return_annotation):
    if what == "class" and is_dataclass(obj):
        return signature.replace("<factory>", "..."), return_annotation

def setup(app):
    app.connect("autodoc-process-signature", process_signature)

@electric-coder electric-coder mentioned this issue Feb 21, 2024
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
extensions:autodoc type:bug
Projects
None yet
Milestone
7.x
Development

No branches or pull requests
3 participants
@AA-Turner @DifferentialOrange @snorkysnark