Add itertoolz.flatten

[groutr]

An implementation of javascript's Array.flat() (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat#use_generator_function) More flexible than the flatten recipe in itertools.

[eriknw]

Cool! yield from syntax from Python 3.3 definitely makes this nicer.

Some questions:

• Isn't flatten a more common name?
• Can you flatten without limit? Should you be able to?
• What about strings, should they be flattened? Should we have some types that we exclude by default or a function to determine what to exclude?
• Alternatively, should we allow types that to recurse into? A function to determine whether to traverse or not would also work.

flatten seems like a useful, well-named function.

[groutr]

Yes, a very good use case for yield from. Some answers:

• Yes, flatten is a good name too. I don't have any strong opinions about the naming. I simply borrowed the name that javascript uses.
• Yes, you actually can flatten without limit. If you choose a high enough integer, or do as javascript does and pass infinity for the level. This particular implementation also has the neat behavior that negative values also behave like infinity. We could allow -1 as a special value to flatten all levels. Technically, we are limited by the recursion limit in Python (so a depth of 3000). If that proves a problematic limit, we can look at a stack based implementation.

• That would be a good addition. I have to admit I didn't test on strings since my use case was flattening what was essentially an ndarray (but without numpy). I have a version that accepts a function to determine if the traverse into an iterable. A nice default would be to exempt str, bytes, bytearray, and dict.

  def example_descend(x):
  return not isinstance(x, (str, bytes, bytearray, dict))
  def flatten(level, seq, descend=None):
  """ Flatten a possible nested sequence by n levels """
  if not callable(descend):
      raise ValueError("descend must be callable boolean function")
  
  if level < -1:
      # -1 flattens infinitely.
      raise ValueError("Level must be >=0 or -1")
  
  def flat(level, seq):
      if level == 0:
          yield from seq
          return
  
      for item in seq:
          if isiterable(item) and descend(item):
              yield from flat(level - 1, item)
          else:
              yield item
  
  yield from flat(level, seq)

  The descend function is only called on iterable items and returns True if the iterable should be unpacked. If this looks better to you, I can go ahead and commit it.

@eriknw I really appreciate the feedback.

[groutr]

@eriknw I think this is ready for another review.

[groutr]

ping @eriknw