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
Typing pending_xref
node attrributes (and maybe all addnodes
)
#12208
Comments
Ah yes, the
It becomes "required" in the sense that
The standard domain is always present, so the corresponding transformations and post-transformations as well. In particular, when you call Now, we should have added a better comment or be sure that the only remaining |
As for your original question: yes and no. Yes for common attributes that are known to exist, but that's not always the case (like, |
I'm not familiar with this part of the code base, so my comments will be general rather than specific. Sphinx uses 'stringly-typed' interfaces in a lot of places by using a dict-like interface for many objects. As you observed, often without default arguments or error handling. That doesn't imply it's a bug, more likely the author knows some invariant that mypy doesn't. The problem comes if you refactor and unknowingly violate the invariant... If we can refactor more code to be interrogable by mypy then refactoring can become more "fearless" Where we're absolutely certain that a property must always exist on a class or instance of a class then I think it makes sense to create a subclass and set the property in the init method (or potentially as class variables where appropriate) and then access these properties directly rather than through the dict-like interface. |
Well, that is one of the things I'm trying to work out for myst-parser 😅
exactly, amen to that 🙏 |
I'd be happy to move out to property-based interface but I think the choice is mostly historical and docutils motivated. Alternatively, I could suggest having a mypy plugin for that instead because it could be integrated in the current framework without refactoring anything (or barely).
It is expected but I'm not sure that it is necessarily expected at the beginning of the transformation chain. Transformations and post-transformations have different priorities and I'm pretty sure there are some that dynamically add information because their authors know some invariants (that we do not) to process it in the future. |
Currently,
pending_xref
includes no information about what attributes it is expected to have:sphinx/sphinx/addnodes.py
Lines 477 to 485 in bfce4f5
There are definitely some attributes that are expected, i.e. they are accessed with
node['name']
and wouldKeyError
except if the attribute is not present, then there are ones that are maybe optional, i.e. they are accessed withnode.get('name')
I haven't checked if there are actually any open issue, but there definitely seems like there are discrepancies in the code base, here are some examples:
sphinx/sphinx/transforms/post_transforms/__init__.py
Lines 208 to 210 in bfce4f5
here the "check" treats
refdomain
as if it is optional, but then themsg
creation treats it as if it is required 😅sphinx/sphinx/builders/latex/__init__.py
Lines 373 to 375 in bfce4f5
here
refsectname
is treated as required, but if you actually search forrefsectname
in the code base, it is definitely not set in a lot of places:Am I missing something here? How is some of this stuff not excepting?
@danieleades do you have any thoughts on how to type
Node
subclasses, to have some kind of enforcing of available attributes.Ideally it would be enforced for instantiating the node, and for accessing attributes in an existing node, but I know this would be extremely difficult, if not impossible 😏
Also cc @picnixz may have an opinion?
The text was updated successfully, but these errors were encountered: