Tensor docs plus Linting and Typing and Black oh my (#54)

* TENSOR: Apply black and enforce it

* TENSOR: Add isort and pylint. Fix to pass then enforce

* TENSOR: Variety of linked fixes:
* Add mypy type checking
* Update infrastructure for validating package
* Fix doc tests and add more examples

* DOCTEST: Add doctest automatically to regression
* Fix existing failures

* DOCTEST: Fix non-uniform array

* DOCTEST: Fix precision errors in example

* AUTOMATION: Add test directory otherwise only doctests run

* TENSOR: Fix bad rebase from numpy fix

Author: ntjohnson1

.github/workflows/regression-tests.yml

@@ -37,7 +37,7 @@ jobs:
 #        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
     - name: Run tests
       run: |
-        coverage run --source pyttb -m pytest
+        coverage run --source pyttb -m pytest tests/
         coverage report
     - name: Upload coverage to Coveralls
       run: coveralls --service=github

conftest.py

@@ -10,3 +10,13 @@
 def add_packages(doctest_namespace):
     doctest_namespace['np'] = numpy
     doctest_namespace['ttb'] = pyttb
+
+
+def pytest_addoption(parser):
+    parser.addoption('--packaging', action='store_true', dest="packaging",
+                 default=False, help="enable slow packaging tests")
+
+
+def pytest_configure(config):
+    if not config.option.packaging:
+        setattr(config.option, 'markexpr', 'not packaging')

pyproject.toml

@@ -30,3 +30,33 @@ documentation = "https://pyttb.readthedocs.io"
 requires = ["setuptools>=61.0", "numpy", "numpy_groupies", "scipy", "wheel"]
 build-backend = "setuptools.build_meta"
 
+[tool.isort]
+profile = "black"
+
+[tool.pylint]
+# Play nice with black
+max-line-length = 88
+disable="fixme,too-many-lines"
+
+[tool.pylint.basic]
+# To match MATLAB Tensortoolbox styles for clarity
+argument-naming-style = "any"
+class-naming-style = "any"
+variable-naming-style = "any"
+
+[tool.pylint.design]
+# MATLAB Tensortoolbox interface
+max-public-methods = 40
+
+[tool.mypy]
+warn_unused_configs = true
+plugins = "numpy.typing.mypy_plugin"
+
+[[tool.mypy.overrides]]
+module = [
+    "scipy",
+    "scipy.sparse",
+    "scipy.sparse.linalg",
+    "numpy_groupies"
+]
+ignore_missing_imports = true

pytest.ini

@@ -1,6 +1,9 @@
 [pytest]
 markers =
     indevelopment: marks tests as in development, should not be run
+    packaging: slow tests that check formatting over function
 
 filterwarnings =
     ignore:.*deprecated.*:
+
+addopts = --doctest-modules pyttb

pyttb/cp_als.py

@@ -3,7 +3,7 @@
 # U.S. Government retains certain rights in this software.
 
 import pyttb as ttb
-from .pyttb_utils import *
+from pyttb.pyttb_utils import *
 import numpy as np
 
 def cp_als(tensor, rank, stoptol=1e-4, maxiters=1000, dimorder=None,
@@ -51,54 +51,56 @@ def cp_als(tensor, rank, stoptol=1e-4, maxiters=1000, dimorder=None,
 
     Example
     -------
+    Random initialization causes slight pertubation in intermediate results.
+    `...` is our place holder for these numeric values.
     Example using default values ("random" initialization):
 
     >>> weights = np.array([1., 2.])
     >>> fm0 = np.array([[1., 2.], [3., 4.]])
     >>> fm1 = np.array([[5., 6.], [7., 8.]])
     >>> K = ttb.ktensor.from_data(weights, [fm0, fm1])
     >>> np.random.seed(1)
-    >>> M, Minit, output = ttb.cp_als(K.full(), 2)
+    >>> M, Minit, output = ttb.cp_als(K.full(), 2) # doctest: +ELLIPSIS
     CP_ALS:
-     Iter 0: f = 0.9999999836180988 f-delta = 0.9999999836180988
-     Iter 1: f = 0.9999999836180988 f-delta = 0.0
-     Final f = 0.9999999836180988
-    >>> print(M)
+     Iter 0: f = ... f-delta = ...
+     Iter 1: f = ... f-delta = ...
+     Final f = ...
+    >>> print(M) # doctest: +ELLIPSIS
     ktensor of shape 2 x 2
-    weights=[108.47158396   8.61141076]
+    weights=[108.4715... 8.6114...]
     factor_matrices[0] =
-    [[0.41877462 0.39899343]
-     [0.9080902  0.91695378]]
+    [[0.4187... 0.3989...]
+     [0.9080... 0.9169...]]
     factor_matrices[1] =
-    [[0.61888633 0.25815611]
-     [0.78548056 0.96610322]]
-    >>> print(Minit)
+    [[0.6188... 0.2581...]
+     [0.7854... 0.9661...]]
+    >>> print(Minit) # doctest: +ELLIPSIS
     ktensor of shape 2 x 2
     weights=[1. 1.]
     factor_matrices[0] =
-    [[4.17022005e-01 7.20324493e-01]
-     [1.14374817e-04 3.02332573e-01]]
+    [[4.1702...e-01 7.2032...e-01]
+     [1.1437...e-04 3.0233...e-01]]
     factor_matrices[1] =
-    [[0.14675589 0.09233859]
-     [0.18626021 0.34556073]]
+    [[0.1467... 0.0923...]
+     [0.1862... 0.3455...]]
     >>> print(output)
-    {'params': (0.0001, 1000, 1, [0, 1]), 'iters': 1, 'normresidual': 1.9073486328125e-06, 'fit': 0.9999999836180988}
+    {'params': (0.0001, 1000, 1, [0, 1]), 'iters': 1, 'normresidual': ..., 'fit': ...}
 
     Example using "nvecs" initialization:
 
-    >>> M, Minit, output = ttb.cp_als(K.full(), 2, init="nvecs")
+    >>> M, Minit, output = ttb.cp_als(K.full(), 2, init="nvecs") # doctest: +ELLIPSIS
     CP_ALS:
-     Iter 0: f = 1.0 f-delta = 1.0
-     Iter 1: f = 1.0 f-delta = 0.0
-     Final f = 1.0
+     Iter 0: f = ... f-delta = ...
+     Iter 1: f = ... f-delta = ...
+     Final f = ...
 
     Example using :class:`pyttb.ktensor` initialization:
 
-    >>> M, Minit, output = ttb.cp_als(K.full(), 2, init=K)
+    >>> M, Minit, output = ttb.cp_als(K.full(), 2, init=K) # doctest: +ELLIPSIS
     CP_ALS:
-     Iter 0: f = 0.9999999836180988 f-delta = 0.9999999836180988
-     Iter 1: f = 0.9999999836180988 f-delta = 0.0
-     Final f = 0.9999999836180988
+     Iter 0: f = ... f-delta = ...
+     Iter 1: f = ... f-delta = ...
+     Final f = ...
     """
 
     # Extract number of dimensions and norm of tensor
@@ -246,5 +248,5 @@ def cp_als(tensor, rank, stoptol=1e-4, maxiters=1000, dimorder=None,
 
 if __name__ == "__main__":
     import doctest               # pragma: no cover
-    import pyttb as ttb  # pragma: no cover
+
     doctest.testmod()            # pragma: no cover

pyttb/khatrirao.py

@@ -24,11 +24,12 @@ def khatrirao(*listOfMatrices, reverse=False):
 
     Examples
     --------
-    >>>A = np.random.norm(size=(5,2))
-    >>>khatrirao(A,B) #<-- Khatri-Rao of A and B
-    >>>>khatrirao(B,A,reverse=True) #<-- same thing as above
-    >>>>khatrirao([A,A,B]) #<-- passing a list
-    >>>>khatrirao([B,A,A},reverse = True) #<-- same as above
+    >>> A = np.random.normal(size=(5,2))
+    >>> B = np.random.normal(size=(5,2))
+    >>> _ = khatrirao(A,B) #<-- Khatri-Rao of A and B
+    >>> _ = khatrirao(B,A,reverse=True) #<-- same thing as above
+    >>> _ = khatrirao([A,A,B]) #<-- passing a list
+    >>> _ = khatrirao([B,A,A],reverse = True) #<-- same as above
     """
     #Determine if list of matrices of multiple matrix arguments
     if isinstance(listOfMatrices[0], list):