Merge branch 'main' into fix-kmatrix-widget

src/ampform/io/__init__.py

@@ -27,6 +27,8 @@ def aslatex(obj) -> str:
     """Render objects as a LaTeX `str`.
 
     The resulting `str` can for instance be given to `IPython.display.Math`.
+
+    .. versionadded:: 0.14.1
     """
     return str(obj)
 
@@ -76,7 +78,10 @@ def _(obj: Iterable) -> str:
 
 
 def improve_latex_rendering() -> None:
-    """Improve LaTeX rendering of an `~sympy.tensor.indexed.Indexed` object."""
+    """Improve LaTeX rendering of an `~sympy.tensor.indexed.Indexed` object.
+
+    .. versionadded:: 0.14.2
+    """
 
     def _print_Indexed_latex(self, printer, *args):  # noqa: N802
         base = printer._print(self.base)

src/ampform/sympy/__init__.py

@@ -14,13 +14,12 @@
 
 import itertools
 import logging
-import os
 import pickle  # noqa: S403
 import re
 import sys
 import warnings
 from abc import abstractmethod
-from os.path import abspath, dirname
+from pathlib import Path
 from typing import TYPE_CHECKING, Iterable, Sequence, SupportsFloat
 
 import sympy as sp
@@ -43,6 +42,10 @@
     make_commutative,  # pyright: ignore[reportUnusedImport]  # noqa: F401
 )
 
+if sys.version_info < (3, 8):
+    from importlib_metadata import version
+else:
+    from importlib.metadata import version
 if sys.version_info < (3, 12):
     from typing_extensions import override
 else:
@@ -289,6 +292,11 @@ def determine_indices(symbol: sp.Basic) -> list[int]:
 
 
 class UnevaluatableIntegral(sp.Integral):
+    """See :ref:`usage/sympy:Numerical integrals`.
+
+    .. versionadded:: 0.14.10
+    """
+
     abs_tolerance = 1e-5
     rel_tolerance = 1e-5
     limit = 50
@@ -335,7 +343,7 @@ def _warn_if_scipy_not_installed() -> None:
 
 
 def perform_cached_doit(
-    unevaluated_expr: sp.Expr, cache_directory: str | None = None
+    unevaluated_expr: sp.Expr, cache_directory: Path | str | None = None
 ) -> sp.Expr:
     """Perform :meth:`~sympy.core.basic.Basic.doit` and cache the result to disk.
 
@@ -353,15 +361,19 @@ def perform_cached_doit(
         <https://docs.python.org/3/using/cmdline.html#envvar-PYTHONHASHSEED>`_ to a
         fixed value.
 
+    .. versionadded:: 0.14.4
     .. automodule:: ampform.sympy._cache
     """
     if cache_directory is None:
         system_cache_dir = get_system_cache_directory()
-        cache_directory = abspath(f"{system_cache_dir}/ampform")
+        sympy_version = version("sympy")
+        cache_directory = Path(system_cache_dir) / "ampform" / f"sympy-v{sympy_version}"
+    if not isinstance(cache_directory, Path):
+        cache_directory = Path(cache_directory)
+    cache_directory.mkdir(exist_ok=True, parents=True)
     h = get_readable_hash(unevaluated_expr)
-    filename = f"{cache_directory}/{h}.pkl"
-    os.makedirs(dirname(filename), exist_ok=True)
-    if os.path.exists(filename):
+    filename = cache_directory / f"{h}.pkl"
+    if filename.exists():
         with open(filename, "rb") as f:
             return pickle.load(f)  # noqa: S301
     _LOGGER.warning(

src/ampform/sympy/_cache.py

@@ -18,7 +18,7 @@
 def get_system_cache_directory() -> str:
     r"""Return the system cache directory for the current platform.
 
-    >>> import sys, pytest
+    >>> import sys
     >>> if sys.platform.startswith("darwin"):
     ...     assert get_system_cache_directory().endswith("/Library/Caches")
     >>> if sys.platform.startswith("linux"):

src/ampform/sympy/_decorator.py

@@ -92,6 +92,8 @@ def argument(
 
     Creates a :class:`dataclasses.Field` with additional metadata for
     :func:`unevaluated` by wrapping around :func:`dataclasses.field`.
+
+    .. versionadded:: 0.14.8
     """
     return _create_field(
         default=default,
@@ -176,6 +178,10 @@ def unevaluated(
     True
     >>> expr.functor is Transformation
     True
+
+    .. versionadded:: 0.14.8
+    .. versionchanged:: 0.14.7
+        Renamed from :code:`@unevaluated_expression()` to :code:`@unevaluated()`.`
     """
     if assumptions is None:
         assumptions = {}