Differentiating between edge types at the API level

[dhimmel]

I am thinking we want three user-facing functions to perform the permutation. They could be named like:

permute_undirected_edges
permute_directed_edges
permute_bipartite_edges

I think this would be clearest for the user. You could remove the confusing allow_self_loop from permute_bipartite_edges. allow_antiparallel would only be an option for permute_directed_edges. Also permute_undirected_edges could mix sources or targets when swapping to achieve greater potential permutations?

@zietzm, do you think this makes sense?

[dhimmel]

If we go with three different functions, it would be nice to avoid duplication of argument definitions and docstrings. Not sure the best way to do this.

One possible option is to use classes / subclasses. These could be helpful for tracking the stats as well.

[dhimmel]

Another option is that we could have a single function but take an argument like network_type that would have to be in {"undirected", "directed", "bipartite"}.

If we do have three different functions, possibly functools.wraps / functools.update_wrapper could help with avoiding duplicate documentation.