Expectations on input / output of array dimensions and approaches to implement support for variable dimensions input arrays

Question

Preamble

As we are vectorising our colour API, we are changing the accepted input types for most of our functions. We would be keen on keeping backward compatibility with the existing code.

Let's define the following input variables:

numeric

R

shape: ()

A pixel R value of an RGB triplet for example.

1d

[R, G, B]

shape: (3)

A pixel RGB values triplet for example.

2d

[[R, G, B],
 [R, G, B],
 [R, G, B],
 [R, G, B],
 [R, G, B],
 [R, G, B]]

shape: (6, 3)

A line of RGB values triplet for example.

3d

[[[R, G, B],
  [R, G, B],
  [R, G, B]],

 [[R, G, B],
  [R, G, B],
  [R, G, B]]]

shape: (2, 3, 3)

An image of RGB values triplet for example.

Expectations

A function that was previously accepting a numeric as input may now accept a numeric or a 1d array. A function previously accepting a 1d array as input may now accept a 1d, 2d or 3d array.

Most of our codebase vectorisation is now prototyped. Specifically, in order to support 1d, 2d or 3d arrays with functions originally taking a 1d array as input, we convert the input array to a 2d one. The inner algorithms now work with the 2d arrays thus their implementation is straightforward and predictable.

For a given function, as we modify the input array dimensions for its algorithm purpose, the resulting output array dimensions are altered (if we don't do anything about it).

We would like to know the following:

Is trying to maintain the array dimensions a commonly expected behaviour?

A path that seems logical is to maintain the dimensions of the input array: for example we suppose that somebody inputing an image (with a 3d shape) to our RGB_to_XYZ function would probably expect to get an image with a 3d shape, somebody inputing a 1d RGB pixel to that same function would probably expect to get a 1d XYZ pixel in return and not a 2d array.

An alternative path would be to enforce the expected input / output array dimensions for each function (which would break backward compatibility).

Implementations

The alternative path doesn't present any difficulties in its implementation.

The logical path is however trickier: as we have prototyped the code in that regard, we have a lot of redundant boiler plate code at the start and end of each function in order to retrieve the dimensions of the input array, change its dimensions and reshape the output array. This is not very elegant and confusing for somebody reading the code while contributing to a harder maintainability.

Is there an elegant way to implement the "logical" path behaviour?

We are thinking about a wrapper function (decorator as we are using Python) that could be responsible of handling all the dimensions / reshaping wizardry, the functions themselves could then have fixed expectations on the input / output like in the alternative path.

Answer 1

Is trying to maintain the array dimensions a commonly expected behaviour?

To me this sounds a little like "Would people expect my API to do all these type conversions under the hood?" to which the answer is "Probably yes, but they shouldn't care either way, since they shouldn't have to worry about your implementation". Maybe you have a hyper-optimized way of frobnicating colors that only have an R-component, and that "old" overload should be calling it.

If you're trying to ask "Would people expect us to maintain backwards compatibility by supporting all the old types?" then the answer depends entirely on your user base, and we don't know anything about them. For instance, historically Microsoft Windows can't even fix bugs safely, much less change argument types. On the other hand, Python 3 "broke" one of its most basic I/O primitives, and that seems to have worked out okay. Maybe your users would even appreciate having a "clean break" from the old API. It all depends.

Is there an elegant way to implement the "logical" path behaviour?

My solution in C++ would probably look something like this:

class ColorFrobnicator {
  public:
    int frobnicate(const int R) {
        std::vector<int> colors = { R, 0, 0 };
        return actuallyFrobnicate(colors);
    }
    int frobnicate(const std::vector<int>& colors) {
        return actuallyFrobnicate(colors);
    }

  private:
    int actuallyFrobnicate(const std::vector<int>& colors) {
        /* the code that actually matters goes here */
        return finalValueAfterExtensiveFrobnication;
    }
}

I think this is about as "elegant" as backwards compatibility can ever get: Put all the conversions and wrappers up in the interface, and move all the "real code" down into the implementation. That way none of your real code ever has to go if(oldAPI) { convertToArray(R); }, and you can easily make changes to the old or new interfaces without touching the real code.

I don't have all that much experience in Python, but I'm sure there's an equally palatable way of handling this in that language.