How to flatten a list of lists.
chain, comprehension, recursion.

The three methods compared:

chain.from_iterable(nested):
  ✅ Fastest (implemented in C)
  ✅ Lazy — yields items one at a time
  ✅ O(n) memory for the list conversion,
     O(1) if you iterate directly
  ✅ Works with any iterable-of-iterables
  ❌ Requires an import
  ❌ Only flattens one level

List comprehension:
  ✅ Readable
  ✅ No import needed
  ✅ Fast enough for most code
  ✅ Can add conditions inline
  ❌ Builds the whole list (eager)
  ❌ Only flattens one level

sum(nested, []):
  ✅ Shortest syntax
  ❌ O(n²) — unusable for large data
  ❌ Creates a new list at each step
  ❌ Only works with lists (not tuples/strings)
  ❌ Never the right answer

When to use each:

✅ chain.from_iterable — when you need speed
   or are working with large/lazy data:
   
   from itertools import chain
   
   for item in chain.from_iterable(nested):
       process(item)   # memory-efficient
   
   Or:
   flat = list(chain.from_iterable(nested))
   # fastest way to get a flat list

✅ Comprehension — for readability, small data,
   or when you need conditions:
   
   flat = [x for sub in nested for x in sub if x > 0]
   # filter while flattening
   
   flat = [f(x) for sub in nested for x in sub]
   # transform while flattening

❌ sum(nested, []) — never for production code.
   Use chain or comprehension instead.

The common one-liner versions:

  # Shortest:
  sum(nested, [])  # slow
  
  # Fastest:
  list(chain.from_iterable(nested))
  
  # Readable:
  [x for sub in nested for x in sub]

The chain variants:

  chain(nested[0], nested[1], ...)  # multiple args
  chain.from_iterable(nested)       # one iterable
  chain(*nested)                    # unpack — same as above

  For flattening, from_iterable is the right one:
  it takes the outer list and iterates the inner ones.

  chain(*nested) also works but has a size limit —
  the splat operator unpacks everything into one
  call, which fails for huge lists (>~100k items).
  from_iterable doesn't unpack — it iterates.

  So:
    ❌ chain(*nested) for large nested
    ✅ chain.from_iterable(nested) always

⚠️ For a list of strings:
   chain.from_iterable(['ab', 'cd']) gives 'a', 'b', 'c', 'd'
   because chain iterates each string.
   
   If you want ['ab', 'cd'] as flat, it's already flat.
   
   If you want each character as an item:
     [char for s in strings for char in s]
   
   If you want them concatenated:
     ''.join(strings)  # 'abcd'

Why recursion is necessary:

  chain.from_iterable only iterates the OUTER list.
  It yields each inner item as-is — including
  nested lists.
  
  [[1, 2], [3, [4, 5]]] → 1, 2, 3, [4, 5]
                         ^ the [4, 5] is still a list
  
  To go deeper, you need to detect nested lists
  and recurse into them.
  
  That's what the recursive flatten() does:
    for each item:
      if it's a list → recurse
      else          → yield the item
  
  The yield from delegates to the recursive call,
  flattening the result into the parent generator.
  
  This handles arbitrary depth automatically.

The recursion limit:

  Python's default recursion depth is 1000.
  For lists nested deeper than 1000 levels,
  flatten() raises RecursionError.
  
  For most data, this is fine:
    - JSON files rarely nest more than 10 levels
    - Tree structures rarely exceed 50
    - Deep nesting (>100) is usually a bug
  
  For the rare case of very deep nesting,
  use the iterative version with an explicit
  stack. It's slower but avoids the recursion
  limit.
  
  Or increase the limit:
    import sys
    sys.setrecursionlimit(10000)
  
  But this is risky — increasing the limit
  can crash the interpreter if you exceed
  the C stack.

The isinstance check:

  isinstance(item, list) — item is a list?
  
  For mixed types (lists and tuples):
    isinstance(item, (list, tuple))
  
  For any sequence except strings:
    isinstance(item, (list, tuple, set)) or
    hasattr(item, '__iter__') and not isinstance(item, str)
  
  The last one is trickier:
    - Sets are iterable but unordered
    - Dicts are iterable (over keys)
    - Bytes are iterable (over ints)
    - Custom iterables are iterable
  
  For most flatten problems, restrict to lists
  (or lists + tuples). The general "flatten
  anything iterable" case is rarely what you want.

The recursive pattern:

  def flatten(nested):
      for item in nested:
          if isinstance(item, list):
              yield from flatten(item)   # recurse
          else:
              yield item                 # base case

  This is the template. Modify based on:
    - What counts as "nested" (list, tuple, both)
    - Whether to filter items (skip None, skip strings)
    - Whether to transform items

The flatten-with-transform pattern:

  def flatten_map(nested, f):
      for item in nested:
          if isinstance(item, list):
              yield from flatten_map(item, f)
          else:
              yield f(item)
  
  flat = list(flatten_map(data, lambda x: x * 2))

When to use recursion vs chain:

✅ chain.from_iterable — one level of nesting
   → [[1, 2], [3, 4]] — one level
   → Simpler, faster, no recursion limit

✅ Recursion — arbitrary depth
   → [1, [2, [3, 4]]] — multiple levels
   → Handles any nesting depth

✅ Iterative with stack — depth > 1000
   → Extremely deep nesting (rare)
   → Avoids RecursionError

How to tell:

  If you know the structure is one level:
    chain.from_iterable
  If the structure could be any depth:
    flatten() with recursion
  If depth exceeds 1000:
    iterative stack version

For 99% of real code, one level is enough,
and chain.from_iterable is the answer.

String trap explained:

  ['hello', 'world']
  
  These are TWO strings. The list has 2 items.
  But each string is iterable (over characters).
  
  chain.from_iterable iterates the outer list
  AND the inner strings:
  
  outer → 'hello', 'world'
  inner → 'h', 'e', 'l', 'l', 'o', 'w', ...
  
  Result: 10 items, one per character.

When is this wanted:
  → Character-level processing
  → Text analysis
  → Rare

When it's a bug:
  → "I have a list of words, I want the same
    list" — but you get characters
  → Fix: the list is already flat, don't flatten

For "list of sentences, want list of words":
  sentences = ['Hello world', 'How are you']
  words = [w for s in sentences for w in s.split()]
  # ['Hello', 'world', 'How', 'are', 'you']

  Not chain.from_iterable — because you're not
  flattening the sentences, you're splitting them.

For "list of words, want characters":
  chars = list(chain.from_iterable(words))
  # chain is correct here

For "list of words, want joined string":
  text = ''.join(words)

The pattern:

  chain.from_iterable is for "iterable of iterables."
  
  What's iterable:
    → List
    → Tuple
    → Set
    → String  ← the trap
    → Dict (over keys)
    → Generator
    → File (over lines)
    → Range
  
  chain.from_iterable(['ab', 'cd']) iterates
  the strings, yielding characters.
  
  If you want the strings as items, the list is
  already flat — you don't need chain.

NumPy flattening:

  arr = np.array([[1, 2], [3, 4]])

  arr.flatten():
    → Returns a new 1D array
    → Always a copy
    → Works for any array (2D, 3D, ...)
    → Safe: modifying the result doesn't
      affect the original

  arr.ravel():
    → Returns a view (if possible)
    → Modifying the result MAY affect the
      original
    → Faster (no copy)
    → Only for contiguous arrays
    → Use when you're reading, not writing

  arr.reshape(-1):
    → Also returns a view
    → -1 means "figure out this dimension"
    → Equivalent to ravel() for most cases

  For flattening:
    ✅ ravel() for read-only
    ✅ flatten() when you need a copy
    ✅ reshape(-1) — same as ravel

  Performance:
    For a 1000x1000 array:
      ravel:   ~1 μs (view)
      flatten: ~1 ms (copy)
      Python chain: ~100 ms
      Comprehension: ~200 ms
    NumPy is 100-1000x faster for numeric data.

  But NumPy requires:
    → Equal-length sublists (2D array)
    → Same dtype for all items
    → A dependency

  For a one-off flatten of a small list,
  chain.from_iterable is fine.
  
  For numeric data in a project already
  using NumPy, ravel() is the right tool.

Dict flattening:

  A dict with nested dicts is a different problem.
  Dicts aren't sequences — they're mappings.
  
  flatten_dict({'a': 1, 'b': {'c': 2}})
  → {'a': 1, 'b.c': 2}
  
  The keys are concatenated with a separator.
  This is used for:
    → Configuration merging
    → JSON path generation
    → Database column names
  
  For a list-of-dicts, you'd use a comprehension
  or chain over the values, but the "flatten"
  concept is different.