sphinx-doc / sphinx-doc/sphinx

app.registry.get_translator_class returns 'property' objects for certain builders.

Open
#9,496 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

api awaiting:response type:question
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

sphinx.builders.html.StandaloneHTMLBuilder uses a property for default_translator_class, but in the base class it's a conventional variable. This means that code using app.registry.get_translator_class for any builder that subclasses StandaloneHTMLBuilder is given a property object rather than the actual nodes.NodeVisitor class.

How to Reproduce

The example conf.py below illustrates what I'm doing:

from docutils.nodes import paragraph

def setup(app):
    builder = app.registry.builders["epub"]
    epub_translator = app.registry.get_translator_class(builder)
    app.add_node(paragraph, epub=(epub_translator.visit_paragraph, epub_translator.depart_paragraph))

Running sphinx-build -M html . ./build -T:

Running Sphinx v4.1.1

Traceback (most recent call last):
  File "venv/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "venv/lib/python3.8/site-packages/sphinx/application.py", line 251, in __init__
    self.config.setup(self)
  File "conf.py", line 7, in setup
    app.add_node(paragraph, epub=(epub_translator.visit_paragraph, epub_translator.depart_paragraph))
AttributeError: 'property' object has no attribute 'visit_paragraph'

Exception occurred:
  File "conf.py", line 7, in setup
    app.add_node(paragraph, epub=(epub_translator.visit_paragraph, epub_translator.depart_paragraph))
AttributeError: 'property' object has no attribute 'visit_paragraph'
The full traceback has been saved in /tmp/sphinx-err-46tp_ln9.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Expected behavior

The default_translator_class attribute, and app.registry.get_translator_class, should always returns a nodes.NodeVisitor class, per the type annotations on both.

Your project

N/A

Screenshots

No response

OS

Ubuntu 20.04

Python version

3.8.10

Sphinx version

2.0.0 - 4.1.1

Sphinx extensions

None

Extra tools

None

Additional context

The offending code is here:
https://github.com/sphinx-doc/sphinx/blob/07598f0d6f3208a6c5e8c20a381730cbb45544b2/sphinx/builders/html/__init__.py#L335-L340

I suspect the # type: ignore is there because mypy was warning about exactly this issue. If I remove the comment I get an (albeit cryptic) error:

sphinx/builders/html/__init__.py: note: In class "StandaloneHTMLBuilder":
sphinx/builders/html/__init__.py:336:5: error: Signature of "default_translator_class" incompatible with supertype "Builder"

mypy has determined the signature to be def (self: sphinx.builders.html.StandaloneHTMLBuilder) -> Type[docutils.nodes.NodeVisitor].

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 in sphinx/builders/html/init.py at StandaloneHTMLBuilder.default_translator_class, then trace app.registry.get_translator_class and the base Builder definition. Reproduce the issue with the provided conf.py example and verify that the registry returns a nodes.NodeVisitor class with visit_paragraph and depart_paragraph attributes rather than a property object.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.