class_docstr: Place a legend on the figure/axes.
class_docstr_tok: ["Place","a","legend","on","the","figure\/axes","."]
docstr: Initialize the legend_box. The legend_box is an instance of
  the OffsetBox, which is packed with legend handles and
  texts. Once packed, their location is calculated during the
  drawing time.
docstr_tok: ["Initialize","the","legend_box",".","The","legend_box","is","an","instance","of","the","OffsetBox",",","which","is","packed","with","legend","handles","and","texts",".","Once","packed",",","their","location","is","calculated","during","the","drawing","time","."]
code: def _init_legend_box(self, handles, labels, markerfirst=True):
      """
      Initialize the legend_box. The legend_box is an instance of
      the OffsetBox, which is packed with legend handles and
      texts. Once packed, their location is calculated during the
      drawing time.
      """
  
      fontsize = self._fontsize
  
      # legend_box is a HPacker, horizontally packed with columns.
      # Each column is a VPacker, vertically packed with legend items.
      # Each legend item is a HPacker packed with:
      # - handlebox: a DrawingArea which contains the legend handle.
      # - labelbox: a TextArea which contains the legend text.
  
      text_list = []  # the list of text instances
      handle_list = []  # the list of handle instances
      handles_and_labels = []
  
      # The approximate height and descent of text. These values are
      # only used for plotting the legend handle.
      descent = (
          0.35 * fontsize * (self.handleheight - 0.7)
      )  # heuristic.
      height = fontsize * self.handleheight - descent
      # each handle needs to be drawn inside a box of (x, y, w, h) =
      # (0, -descent, width, height).  And their coordinates should
      # be given in the display coordinates.
  
      # The transformation of each handle will be automatically set
      # to self.get_transform(). If the artist does not use its
      # default transform (e.g., Collections), you need to
      # manually set their transform to the self.get_transform().
      legend_handler_map = self.get_legend_handler_map()
  
      for orig_handle, label in zip(handles, labels):
          handler = self.get_legend_handler(
              legend_handler_map, orig_handle
          )
          if handler is None:
              _api.warn_external(
                  "Legend does not support handles for "
                  f"{type(orig_handle).__name__} "
                  "instances.\nA proxy artist may be used "
                  "instead.\nSee: https://matplotlib.org/"
                  "stable/users/explain/axes/legend_guide.html"
                  "#controlling-the-legend-entries"
              )
              # No handle for this artist, so we just defer to None.
              handle_list.append(None)
          else:
              textbox = TextArea(
                  label,
                  multilinebaseline=True,
                  textprops=dict(
                      verticalalignment="baseline",
                      horizontalalignment="left",
                      fontproperties=self.prop,
                  ),
              )
              handlebox = DrawingArea(
                  width=self.handlelength * fontsize,
                  height=height,
                  xdescent=0.0,
                  ydescent=descent,
              )
  
              text_list.append(textbox._text)
              # Create the artist for the legend which represents the
              # original artist/handle.
              handle_list.append(
                  handler.legend_artist(
                      self, orig_handle, fontsize, handlebox
                  )
              )
              handles_and_labels.append((handlebox, textbox))
  
      columnbox = []
      # array_split splits n handles_and_labels into ncols columns, with the
      # first n%ncols columns having an extra entry.  filter(len, ...)
      # handles the case where n < ncols: the last ncols-n columns are empty
      # and get filtered out.
      for handles_and_labels_column in filter(
          len, np.array_split(handles_and_labels, self._ncols)
      ):
          # pack handlebox and labelbox into itembox
          itemboxes = [
              HPacker(
                  pad=0,
                  sep=self.handletextpad * fontsize,
                  children=[h, t] if markerfirst else [t, h],
                  align="baseline",
              )
              for h, t in handles_and_labels_column
          ]
          # pack columnbox
          alignment = "baseline" if markerfirst else "right"
          columnbox.append(
              VPacker(
                  pad=0,
                  sep=self.labelspacing * fontsize,
                  align=alignment,
                  children=itemboxes,
              )
          )
  
      mode = "expand" if self._mode == "expand" else "fixed"
      sep = self.columnspacing * fontsize
      self._legend_handle_box = HPacker(
          pad=0,
          sep=sep,
          align="baseline",
          mode=mode,
          children=columnbox,
      )
      self._legend_title_box = TextArea("")
      self._legend_box = VPacker(
          pad=self.borderpad * fontsize,
          sep=self.labelspacing * fontsize,
          align=self._alignment,
          children=[self._legend_title_box, self._legend_handle_box],
      )
      self._legend_box.set_figure(self.figure)
      self._legend_box.axes = self.axes
      self.texts = text_list
      self.legend_handles = handle_list
  
imports: import itertools
  import logging
  import numbers
  import time
  import numpy
  import matplotlib
  from matplotlib import _api, _docstring, colors, offsetbox
  from matplotlib.artist import Artist, allow_rasterization
  from matplotlib.cbook import silent_list
  from matplotlib.font_manager import FontProperties
  from matplotlib.lines import Line2D
  from matplotlib.patches import Patch, Rectangle, Shadow, FancyBboxPatch, StepPatch
  from matplotlib.collections import Collection, CircleCollection, LineCollection, PathCollection, PolyCollection, RegularPolyCollection
  from matplotlib.text import Text
  from matplotlib.transforms import Bbox, BboxBase, TransformedBbox
  from matplotlib.transforms import BboxTransformTo, BboxTransformFrom
  from matplotlib.offsetbox import AnchoredOffsetbox, DraggableOffsetBox, HPacker, VPacker, DrawingArea, TextArea
  from matplotlib.container import ErrorbarContainer, BarContainer, StemContainer
  from .None import legend_handler
label_desc: Use image node_id 15 for calling the Legend obj's underlying member method code with example usage: obj._init_legend_box(handles, labels, markerfirst) without return types