title: What does the "yield" keyword do?
body: <p>What is the use of the <code>yield</code> keyword in Python? What does it do?</p>
  <p>For example, I'm trying to understand this code<sup><strong>1</strong></sup>:</p>
  <pre><code>def _get_child_candidates(self, distance, min_dist, max_dist):
      if self._leftchild and distance - max_dist &lt; self._median:
          yield self._leftchild
      if self._rightchild and distance + max_dist &gt;= self._median:
          yield self._rightchild  
  </code></pre>
  <p>And this is the caller:</p>
  <pre><code>result, candidates = [], [self]
  while candidates:
      node = candidates.pop()
      distance = node._get_dist(obj)
      if distance &lt;= max_dist and distance &gt;= min_dist:
          result.extend(node._values)
      candidates.extend(node._get_child_candidates(distance, min_dist, max_dist))
  return result
  </code></pre>
  <p>What happens when the method <code>_get_child_candidates</code> is called?
  Is a list returned? A single element? Is it called again? When will subsequent calls stop?</p>
  <hr />
  <sub>
  1. This piece of code was written by Jochen Schulz (jrschulz), who made a great Python library for metric spaces. This is the link to the complete source: <a href="https://well-adjusted.de/~jrspieker/mspace/" rel="noreferrer">Module mspace</a>.</sub>