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 theorientations argument toSankey.add:

1. Confusing error message iflen(flows) > 2 andorientations not specified

Repro:

frommatplotlib.sankeyimportSankeysankey=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 thatorientations has length 2? I didn't specify a value, and its default value isNone.

Also,orientations is listed as anoptional 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 ofprior orconnect and not get an exception).

2. Passing a scalar fororientations fails

labels andpathlengths 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 fororientations. e.g. the following fails withTypeError: object of type 'int' has no len():

frommatplotlib.sankeyimportSankeysankey=Sankey()sankey.add(flows=[1,-.33,-.67],orientations=0,)sankey.finish()

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

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

Iforientations == 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