Edit by @anntzer: The main issue reported below has been fixed in #13213, but #13184 (comment) remains; the issue title has been edited accordingly.

I encountered a couple issues with the orientations argument to Sankey.add:

1. Confusing error message if len(flows) > 2 and orientations not specified

Repro:

from matplotlib.sankey import Sankey
sankey = Sankey()
sankey.add(
    flows=[1, -.33, -.67],
)
sankey.finish()

This gives:

ValueError: orientations and flows must have the same length.
orientations has length 2, but flows has length 3.

Expected: Some reasonable default behaviour, or a comprehensible error message.

Why is it saying that orientations has length 2? I didn't specify a value, and its default value is None.

Also, orientations is listed as an optional keyword argument, so the fact that this fails at all is a little surprising. It seems like all the other arguments in the list are truly optional (I can even specify exactly one of prior or connect and not get an exception).

2. Passing a scalar for orientations fails

labels and pathlengths can be passed as either a list, or a single string/number. If a scalar is passed, it's treated as a list with that scalar repeated the appropriate number of times.

This is not the case for orientations. e.g. the following fails with TypeError: object of type 'int' has no len():

from matplotlib.sankey import Sankey
sankey = Sankey()
sankey.add(
    flows=[1, -.33, -.67],
    orientations=0,
)
sankey.finish()

Expected: No exception. Behaviour equivalent to if I had passed orientations=[0, 0, 0].

The docs suggest this should work, per the following quote from the docstring:

If orientations == 0, inputs will break in from the left and outputs will break away to the right.

Matplotlib version

• Operating system: Ubuntu 16.04
• Matplotlib version: 3.0.2 (installed via pip)
• Matplotlib backend (print(matplotlib.get_backend())): module://ipykernel.pylab.backend_inline
• Python version: 3.5.2