Closed antonagestam closed 2 years ago
Thanks for raising this! Obviously, numerary
shouldn't break doc generation. If it does, that should be fixed.
I saw something (superficially) similar that came up during my attempt to port numerary
's caching functionality to beartype
(beartype/beartype#86). I'm wondering if it's related. I think we can get to the bottom of this, though. Let me take a lookβ¦.
What's the workflow you use that generates that error? Is it something like UPDATE: Yup. That looks like it lands on the same issue. Choking on pip install --requirement docs/requirements.txt && make -C docs html
?phantom-types/src/phantom/sized.py
#L27 among several other places.
@posita I think I've found something interesting, if I fire up a normal Python REPL in my project, I can do this as expected:
>>> from numerary import RealLike
>>> isinstance(RealLike, type)
True
But if I put in a breakpoint()
within my code and run the sphinx build, I get this:
(Pdb) from numerary import RealLike
(Pdb) isinstance(RealLike, type)
False
I have no idea why yet, but it seems highly relevant ... π€
Edit: also this:
>>> type(RealLike)
<class 'numerary.types.CachingProtocolMeta'>
(Pdb) type(RealLike)
<class 'numerary.RealLike'>
Thanks! I did take a look at this and was equally stupefied. Rest assured I haven't forgotten about you! I'm working with the beartype project on some mods to the underlying protocol that may help with this. (Please! I hope! π€π) I'm also hoping to make resolving #10 more straightforward. Apologies for the apparent lack of progress on this. Still digging in!
@posita No worries, take your time π
I think I found the issue! The (good?) news is that it wasn't what I thought it was, so thanks for the nudge!
For some reason, at some point, your Sphinx build process invokes something that ends up with typing.TYPE_CHECKING
set to True
and then (re?)loads numerary.numerary.types
, which ends up here:
if TYPE_CHECKING:
# Warning: Deep typing voodoo ahead. See
# <https://github.com/python/mypy/issues/11614>.
from abc import ABCMeta as _ProtocolMeta # <-- this is a lie that is only there for type-checking; it should never be executed at runtime
else:
_ProtocolMeta = type(Protocol)
I discovered this by adding the following lines to numerary/numerary/types.py
immediately prior to where the exception occurs:
if not issubclass(CachingProtocolMeta, (type(_SupportsAbs), type(Protocol))):
breakpoint()
Once that triggered, it allowed me to inspect CachingProtocolMeta
:
(Pdb) CachingProtocolMeta.__bases__
(<class 'abc.ABCMeta'>,)
(Pdb) TYPE_CHECKING
True
Yikes. π¬
The documentation for typing.TYPE_CHECKING
reads, unequivocally (emphasis mine):
A special constant that is assumed to be
True
by 3rd party static type checkers. It isFalse
at runtime.
So TYPE_CHECKING
should never be True
during execution. It doesn't appear to be set to True
anywhere in the standard library (despite suspiciously showing up in the docs for importlib
).
I'm pretty sure this is on sphinx-autodoc-typehints
. How do I know? This is about as close to a smoking gun as one can find:
% find ~/.virtualenvs/phantom-types/lib/python3.9/site-packages -type f -print0 | xargs -0 grep -E 'TYPE_CHECKING.*=.*True'
β¦/.virtualenvs/phantom-types/lib/python3.9/site-packages/sphinx_autodoc_typehints.py: typing.TYPE_CHECKING = True
Yowza. π€― (As an aside, some of these are cringe worthy.)
I updated my clone of your repo via pip install --upgrade 'sphinx-autodoc-typehints>=0.15.3' 'furo==2022.01.02'
and the error went away. The update of furo
is to resolve this warning that appears when upgrading sphinx-autodoc-typehints
alone, namely:
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
furo 2021.4.11b34 requires sphinx~=3.0, but you have sphinx 4.4.0 which is incompatible.
Are you able to upgrade? If so, can you verify on your end?
Oh jeez, that's some exceptional digging! π€― I'll look into upgrading the docs dependencies. Beers are on me if you're ever in Gothenburg, Sweden!
It looks like this solved the whole thing, docs built fine on main
and I'm about to push out a patch release. Thanks again! π₯³
Hi again π
When adding numerary to phantom-types I forgot to update the dependencies of the docs build, which left two sections empty π¬ I'll need to work on the CI so that it blows up earlier for that, and obviously fix the missing imports.
However, as I'm trying to reproduce this failure locally (was a silent warning in CI), I get the traceback below. It seems to indicate that numerary has a metaclass conflict, which confuses me profoundly since both your and my test suites are passing. It's also not reproduced when I in the same environment fire up a REPL and do
from phantom.sized import *
.It seems very likely that isn't really an issue with numerary but rather with my sphinx/autodoc setup, but I it seemed worth reaching out here in case someone has ran into similar issues. Feel free to instantly close this though as I doubt it's actionable within numerary.