From f8651dffdae45e706849fcd506a6093daf789c7f Mon Sep 17 00:00:00 2001
From: Nao Pross <np@0hm.ch>
Date: Sat, 25 May 2024 15:47:30 +0200
Subject: Docstrings and type corrections

---
 polymatrix/expression/from_.py | 29 ++++++++++++++++++++++-------
 polymatrix/expression/init.py  |  2 +-
 2 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/polymatrix/expression/from_.py b/polymatrix/expression/from_.py
index a66580d..65b636d 100644
--- a/polymatrix/expression/from_.py
+++ b/polymatrix/expression/from_.py
@@ -9,17 +9,22 @@ import polymatrix.expression.init as init
 
 from polymatrix.expression.mixins.expressionbasemixin import ExpressionBaseMixin
 from polymatrix.expression.typing import FromSupportedTypes
+from polymatrix.expressionstate import ExpressionState
 from polymatrix.statemonad import StateMonad
+from polymatrix.polymatrix.mixins import PolyMatrixMixin
+from polymatrix.utils.deprecation import deprecated
 
 from polymatrix.expression.expression import (
-    init_expression,
-    Expression,
-    init_variable_expression,
-    VariableExpression
+    init_expression, Expression,
+    init_variable_expression, VariableExpression
 )
 
 
 def from_any(value: FromSupportedTypes) -> Expression:
+    """
+    Attempt create an expression object from a value. Raises an exception if
+    the expression cannot be constructed from given value.
+    """
     if v := from_any_or(value, None):
         return v
 
@@ -28,6 +33,10 @@ def from_any(value: FromSupportedTypes) -> Expression:
 
 
 def from_any_or(value: FromSupportedTypes, value_if_not_supported: Any) -> Expression | Any:
+    """
+    Create an expression object from a value, or give value_if_not_supported if
+    the expression cannot be constructed from the given value.
+    """
     if isinstance(value, VariableExpression | Expression):
         return value
 
@@ -91,7 +100,7 @@ def from_numbers(nums: Iterable[int | float] | Iterable[Iterable[int | float]])
 
     # Row vector
     if isinstance(numbers[0], int | float):
-        return init_expression(init.init_from_numbers_expr((numbers,)))
+        return init_expression(init.init_from_numbers_expr((tuple(numbers),)))
 
     # Matrix
     numbers = tuple(tuple(n) for row in numbers for n in row)
@@ -103,20 +112,26 @@ def from_numpy(array: NDArray) -> Expression:
     return init_expression(init.init_from_numpy_expr(array))
 
 
-def from_state_monad(monad: StateMonad) -> Expression:
+def from_state_monad(monad: StateMonad[ExpressionState, ExpressionBaseMixin | PolyMatrixMixin]) -> Expression:
+    """
+    Create an expression from a StateMonad that returns an expression or
+    polymatrix.
+    """
     return init_expression(init.init_from_statemonad(monad))
 
 
 def from_sympy(expr: sympy.Matrix | sympy.Expr | tuple[tuple[sympy.Expr, ...], ...]) -> Expression:
+    """ Convert a sympy expression into an Expression. """
     return init_expression(init.init_from_sympy_expr(expr))
 
 
 # -- Old API --
 
-
+@deprecated(from_any_or)
 def from_expr_or_none(data: FromSupportedTypes) -> Expression | None:
     return from_any_or(data, None)
 
 
+@deprecated(from_any)
 def from_(*args, **kwargs) -> Expression:
     return from_any(*args, **kwargs)
diff --git a/polymatrix/expression/init.py b/polymatrix/expression/init.py
index b51b92c..abe0c1b 100644
--- a/polymatrix/expression/init.py
+++ b/polymatrix/expression/init.py
@@ -149,7 +149,7 @@ def init_from_numpy_expr(data: npt.NDArray):
     return polymatrix.expression.impl.FromNumpyExprImpl(data=data)
 
 
-def init_from_sympy_expr(data: sympy.Expr | sympy.Matrix | tuple[tuple[sympy.Expr]]):
+def init_from_sympy_expr(data: sympy.Expr | sympy.Matrix | tuple[tuple[sympy.Expr, ...], ...]):
     return polymatrix.expression.impl.FromSympyExprImpl(data=data)
 
 
-- 
cgit v1.2.1