Improve typing docs

doc/conf.py

@@ -33,14 +33,16 @@
 }
 
 
+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

pymbolic/interop/maxima.py

@@ -53,8 +53,9 @@
 OUT_PROMPT_RE = re.compile(br"\(%o([0-9]+)\) ")
 ERROR_PROMPT_RE = re.compile(
     br"(Principal Value|debugmode|incorrect syntax|Maxima encountered a Lisp error)")
-ASK_RE = re.compile(br"(zero or nonzero|an integer|positive, negative, or zero|"
-        b"positive or negative|positive or zero)")
+ASK_RE = re.compile(
+        br"(zero or nonzero|an integer|positive, negative, or zero|"
+        br"positive or negative|positive or zero)")
 MULTI_WHITESPACE = re.compile(br"[ \r\n\t]+")
 
 

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 @@
 # 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 @@
 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")
 

pymbolic/version.py

@@ -6,7 +6,7 @@
 def _parse_version(version: str) -> tuple[tuple[int, ...], str]:
     import re
 
-    m = re.match("^([0-9.]+)([a-z0-9]*?)$", VERSION_TEXT)
+    m = re.match(r"^([0-9.]+)([a-z0-9]*?)$", VERSION_TEXT)
     assert m is not None
 
     return tuple(int(nr) for nr in m.group(1).split(".")), m.group(2)