Pfthb

In my newbie Python 3.7 project, the arguments in many functions are numpy.ndarray's. These must be two-dimensional r x n matrices. The row dimension r is essential: some functions require 1 x n vectors, others 2 x n matrices, with r up to three and possibly more. There're also functions defined for any r x n array. (The column dimension n is not essential for design purposes.)

From my Matlab experience, this requirement can get confusing and error-prone. So I've considered the following approaches:

1. Document the method arguments (of course!)


2. Unit tests (of course!)


3. Do validation and throw exceptions inside some functions. (However, this is not very functional, nor performant.)


4. Define data classes: OneRow, TwoRows, ThreeRows and FourPlusRows. Each has an ndarray field, validated in the constructor. The upside includes type hints and a better domain modelling, a la DDD. A downside is extra complexity.

Question: Given the type hints introduced in Python 3 and the trend towards functional programming, what's the current pythonic approach to this problem?

One of the best things about Python is duck typing, and Numpy is in general very compatible with that design approach. Say you have a vector-only function vecfunc. You can add some boilerplate to the beginning of the function that will inflate any 1D arrays into 1 x n vectors:

def vecfunc(arr):
 if arr.ndim==1:
 arr = arr[None, :]

 ...function body goes here...

This will avoid any problems due to arr having too few dimensions, and will likely still give correct behavior in most cases. However, it doesn't do anything to prevent a user from passing in, say, a r x n x m array, or a 15 x n array. Ultimately, you're going to have to go with approach 3. for a bunch of this stuff and just throw some exceptions where it seems appropriate. For example:

def vecfunc(arr):
 if not 0 < arr.ndim < 3:
 raise ValueError("arr must have ndim of 1 or 2. arr.ndim: %d" % arr.ndim)
 elif arr.ndim==1:
 arr = arr[None, :]

If it makes you feel any better, the code bases of both numpy and scipy have those kinds of shape-based exception checks in a number of functions, when and where they're needed.

Of course, you could always leave off adding those kinds of exception checks until the very end of developing any given function. You may be surprised at the range of input that produces reasonable behavior.

If you're dead set on type annotations, you can get something similar by writing your code using Cython. For example, if you wanted an add function that only took 2D integer arrays, you could write the following function in a .pyx file:

import numpy as np

def add(long[:, :] arr1, long[:, :] arr2):
 assert tuple(arr1.shape) == tuple(arr2.shape)

 result = np.zeros((arr1.shape[0], arr1.shape[1]), dtype=np.long)
 cdef long[:, :] result_view = result

 for x in range(arr1.shape[0]):
 for y in range(arr1.shape[1]):
 result_view[x, y] = arr1[x, y] + arr2[x, y]

 return result

For more details on writing and compiling Cython, see the docs linked above.

This isn't so much "type annotations" as it is actual strong typing, but it may do what you want. Sadly, I wasn't able to find a way to fix the size of a single dimension, just the total number of dimensions.