diff --git a/doc/conf.py b/doc/conf.py index 039bab0fee5537f1cc5e44002981e2692c9d96bf..3b20a6ac703b72fd97dc4717b9f8e7e593cf7cd6 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -33,14 +33,16 @@ autodoc_type_aliases = { } +import sys + + nitpick_ignore_regex = [ - # Avoids this error. Not sure where to even look. + # Avoids this error in pymbolic.typing. # <unknown>:1: WARNING: py:class reference target not found: ExpressionNode [ref.class] # noqa: E501 + # Understandable, because typing can't import primitives, which would be needed + # to resolve the reference. ["py:class", r"ExpressionNode"], ] -import sys - - sys._BUILDING_SPHINX_DOCS = True diff --git a/pymbolic/typing.py b/pymbolic/typing.py index 05630cf50225abc9edbabd08796cf31e92e11077..d1bf82e7522e0a6a9e8c4019d97758a4fa1e7968 100644 --- a/pymbolic/typing.py +++ b/pymbolic/typing.py @@ -1,33 +1,29 @@ """ -.. currentmodule:: pymbolic - Typing helpers -------------- +.. currentmodule:: pymbolic + .. autoclass:: Bool .. autoclass:: Number .. autoclass:: Scalar -.. autoclass:: ArithmeticExpression +.. autodata:: ArithmeticExpression - A narrower type alias than :class:`Expression` that is returned by - arithmetic operators, to allow continue doing arithmetic with the result - of arithmetic. + A narrower type alias than :class:`~pymbolic.typing.Expression` that is returned + by arithmetic operators, to allow continue doing arithmetic with the result. .. currentmodule:: pymbolic.typing -.. autoclass:: Expression +.. autodata:: Expression .. note:: - For backward compatibility, ``pymbolic.Expression`` - will alias :class:`pymbolic.primitives.ExpressionNode` for now. Once its deprecation + For backward compatibility, ``pymbolic.Expression`` will alias + :class:`pymbolic.primitives.ExpressionNode` for now. Once its deprecation period is up, it will be removed, and then, in the further future, ``pymbolic.Expression`` may become this type alias. .. autoclass:: ArithmeticOrExpressionT - - A type variable that can be either :data:`ArithmeticExpression` - or :data:`Expression`. """ from __future__ import annotations @@ -78,7 +74,7 @@ from pytools import module_getattr_for_deprecations # https://github.com/python/typeshed/blob/119cd09655dcb4ed7fb2021654ba809b8d88846f/stdlib/numbers.pyi if TYPE_CHECKING: - from pymbolic.primitives import ExpressionNode + from pymbolic import ExpressionNode # Experience with depending packages showed that including Decimal and Fraction # from the stdlib was more trouble than it's worth because those types don't cleanly @@ -111,16 +107,20 @@ else: Number: TypeAlias = Integer | InexactNumber Scalar: TypeAlias = Number | Bool -_ScalarOrExpression = Union[Scalar, "ExpressionNode"] ArithmeticExpression: TypeAlias = Union[Number, "ExpressionNode"] - -Expression: TypeAlias = _ScalarOrExpression | tuple["Expression", ...] +Expression: TypeAlias = Union[ + Scalar, + "ExpressionNode", + tuple["Expression", ...]] +"""A union of types that are considered as part of an expression tree.""" ArithmeticOrExpressionT = TypeVar( "ArithmeticOrExpressionT", ArithmeticExpression, Expression) - +"""A type variable that can be either an :class:`~pymbolic.ArithmeticExpression` +or an :class:`~pymbolic.typing.Expression`. +""" T = TypeVar("T")