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

DifferentialOrange · 2022-10-03T07:54:17Z

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 [email protected]: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

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

The text was updated successfully, but these errors were encountered:

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

snorkysnark · 2024-01-10T15:16:37Z

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)

DifferentialOrange added the type:bug label Oct 3, 2022

DifferentialOrange mentioned this issue Oct 3, 2022

Sphinx dataclass issue tarantool/tarantool-python#234

Closed

AA-Turner modified the milestones: 5.x, 6.x, 5.3.0 Oct 4, 2022

AA-Turner added the extensions:autodoc label Oct 13, 2022

AA-Turner modified the milestones: 5.3.0, 6.x Oct 15, 2022

timmysilv mentioned this issue Jan 11, 2023

add ExecutionConfig class PennyLaneAI/pennylane#3614

Merged

4flixt mentioned this issue Apr 26, 2023

Settings dataclass in MPC, MHE etc. with field and default_factory: Error in sphinx documentation do-mpc/do-mpc#369

Open

AA-Turner modified the milestones: 6.x, 7.x Apr 29, 2023

electric-coder mentioned this issue Feb 21, 2024

[tracker] Issues related to autodoc and "undefined reference" #11991

Open

AA-Turner modified the milestones: 7.x, 8.x Jul 20, 2024

fzimmermann89 mentioned this issue Jan 7, 2025

Improve documentation PTB-MR/mrpro#598

Merged

AA-Turner modified the milestones: 8.x, some future version Jan 12, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

DifferentialOrange commented Oct 3, 2022 •

edited

Loading

snorkysnark commented Jan 10, 2024

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

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

Comments

DifferentialOrange commented Oct 3, 2022 • edited Loading

Describe the bug

How to Reproduce

Expected behavior

Your project

Screenshots

OS

Python version

Sphinx version

Sphinx extensions

Extra tools

Additional context

snorkysnark commented Jan 10, 2024

DifferentialOrange commented Oct 3, 2022 •

edited

Loading