class_docstr: Place a legend on the axes at location loc.
class_docstr_tok: ["Place","a","legend","on","the","axes","at","location","loc","."]
docstr: Parameters
  ----------
  parent : `~matplotlib.axes.Axes` or `.Figure`
      The artist that contains the legend.
  
  handles : sequence of `.Artist`
      A list of Artists (lines, patches) to be added to the legend.
  
  labels : sequence of strings
      A list of labels to show next to the artists. The length of handles
      and labels should be the same. If they are not, they are truncated
      to the smaller of both lengths.
  
  Other Parameters
  ----------------
  
  loc : int or string or pair of floats, default: 'upper right'
      The location of the legend. Possible codes are:
  
          ===============   =============
          Location String   Location Code
          ===============   =============
          'best'            0
          'upper right'     1
          'upper left'      2
          'lower left'      3
          'lower right'     4
          'right'           5
          'center left'     6
          'center right'    7
          'lower center'    8
          'upper center'    9
          'center'          10
          ===============   =============
  
  
      Alternatively can be a 2-tuple giving ``x, y`` of the lower-left
      corner of the legend in axes coordinates (in which case
      ``bbox_to_anchor`` will be ignored).
  
  bbox_to_anchor : `.BboxBase` or pair of floats
      Specify any arbitrary location for the legend in `bbox_transform`
      coordinates (default Axes coordinates).
  
      For example, to put the legend's upper right hand corner in the
      center of the axes the following keywords can be used::
  
         loc='upper right', bbox_to_anchor=(0.5, 0.5)
  
  ncol : integer
      The number of columns that the legend has. Default is 1.
  
  prop : None or :class:`matplotlib.font_manager.FontProperties` or dict
      The font properties of the legend. If None (default), the current
      :data:`matplotlib.rcParams` will be used.
  
  fontsize : int or float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
      Controls the font size of the legend. If the value is numeric the
      size will be the absolute font size in points. String values are
      relative to the current default font size. This argument is only
      used if `prop` is not specified.
  
  numpoints : None or int
      The number of marker points in the legend when creating a legend
      entry for a `.Line2D` (line).
      Default is ``None``, which will take the value from
      :rc:`legend.numpoints`.
  
  scatterpoints : None or int
      The number of marker points in the legend when creating
      a legend entry for a `.PathCollection` (scatter plot).
      Default is ``None``, which will take the value from
      :rc:`legend.scatterpoints`.
  
  scatteryoffsets : iterable of floats
      The vertical offset (relative to the font size) for the markers
      created for a scatter plot legend entry. 0.0 is at the base the
      legend text, and 1.0 is at the top. To draw all markers at the
      same height, set to ``[0.5]``. Default is ``[0.375, 0.5, 0.3125]``.
  
  markerscale : None or int or float
      The relative size of legend markers compared with the originally
      drawn ones.
      Default is ``None``, which will take the value from
      :rc:`legend.markerscale`.
  
  markerfirst : bool
      If *True*, legend marker is placed to the left of the legend label.
      If *False*, legend marker is placed to the right of the legend
      label.
      Default is *True*.
  
  frameon : None or bool
      Control whether the legend should be drawn on a patch
      (frame).
      Default is ``None``, which will take the value from
      :rc:`legend.frameon`.
  
  fancybox : None or bool
      Control whether round edges should be enabled around the
      :class:`~matplotlib.patches.FancyBboxPatch` which makes up the
      legend's background.
      Default is ``None``, which will take the value from
      :rc:`legend.fancybox`.
  
  shadow : None or bool
      Control whether to draw a shadow behind the legend.
      Default is ``None``, which will take the value from
      :rc:`legend.shadow`.
  
  framealpha : None or float
      Control the alpha transparency of the legend's background.
      Default is ``None``, which will take the value from
      :rc:`legend.framealpha`.  If shadow is activated and
      *framealpha* is ``None``, the default value is ignored.
  
  facecolor : None or "inherit" or a color spec
      Control the legend's background color.
      Default is ``None``, which will take the value from
      :rc:`legend.facecolor`.  If ``"inherit"``, it will take
      :rc:`axes.facecolor`.
  
  edgecolor : None or "inherit" or a color spec
      Control the legend's background patch edge color.
      Default is ``None``, which will take the value from
      :rc:`legend.edgecolor` If ``"inherit"``, it will take
      :rc:`axes.edgecolor`.
  
  mode : {"expand", None}
      If `mode` is set to ``"expand"`` the legend will be horizontally
      expanded to fill the axes area (or `bbox_to_anchor` if defines
      the legend's size).
  
  bbox_transform : None or :class:`matplotlib.transforms.Transform`
      The transform for the bounding box (`bbox_to_anchor`). For a value
      of ``None`` (default) the Axes'
      :data:`~matplotlib.axes.Axes.transAxes` transform will be used.
  
  title : str or None
      The legend's title. Default is no title (``None``).
  
  borderpad : float or None
      The fractional whitespace inside the legend border.
      Measured in font-size units.
      Default is ``None``, which will take the value from
      :rc:`legend.borderpad`.
  
  labelspacing : float or None
      The vertical space between the legend entries.
      Measured in font-size units.
      Default is ``None``, which will take the value from
      :rc:`legend.labelspacing`.
  
  handlelength : float or None
      The length of the legend handles.
      Measured in font-size units.
      Default is ``None``, which will take the value from
      :rc:`legend.handlelength`.
  
  handletextpad : float or None
      The pad between the legend handle and text.
      Measured in font-size units.
      Default is ``None``, which will take the value from
      :rc:`legend.handletextpad`.
  
  borderaxespad : float or None
      The pad between the axes and legend border.
      Measured in font-size units.
      Default is ``None``, which will take the value from
      :rc:`legend.borderaxespad`.
  
  columnspacing : float or None
      The spacing between columns.
      Measured in font-size units.
      Default is ``None``, which will take the value from
      :rc:`legend.columnspacing`.
  
  handler_map : dict or None
      The custom dictionary mapping instances or types to a legend
      handler. This `handler_map` updates the default handler map
      found at :func:`matplotlib.legend.Legend.get_legend_handler_map`.
  
  Notes
  -----
  
  Users can specify any arbitrary location for the legend using the
  *bbox_to_anchor* keyword argument. bbox_to_anchor can be an instance
  of BboxBase(or its derivatives) or a tuple of 2 or 4 floats.
  See :meth:`set_bbox_to_anchor` for more detail.
  
  The legend location can be specified by setting *loc* with a tuple of
  2 floats, which is interpreted as the lower-left corner of the legend
  in the normalized axes coordinate.
docstr_tok: ["Parameters","--","--","--","--","--","parent",":","`","~matplotlib.axes.Axes","`","or","`",".Figure","`","The","artist","that","contains","the","legend",".","handles",":","sequence","of","`",".Artist","`","A","list","of","Artists","(","lines",",","patches",")","to","be","added","to","the","legend",".","labels",":","sequence","of","strings","A","list","of","labels","to","show","next","to","the","artists",".","The","length","of","handles","and","labels","should","be","the","same",".","If","they","are","not",",","they","are","truncated","to","the","smaller","of","both","lengths",".","Other","Parameters","--","--","--","--","--","--","--","--","loc",":","int","or","string","or","pair","of","floats",",","default",":","'upper","right'","The","location","of","the","legend",".","Possible","codes","are",":","===============","=============","Location","String","Location","Code","===============","=============","'best","'","0","'upper","right","'","1","'upper","left","'","2","'lower","left","'","3","'lower","right","'","4","'right","'","5","'center","left","'","6","'center","right","'","7","'lower","center","'","8","'upper","center","'","9","'center","'","10","===============","=============","Alternatively","can","be","a","2-tuple","giving","``","x",",","y","``","of","the","lower-left","corner","of","the","legend","in","axes","coordinates","(","in","which","case","``","bbox_to_anchor","``","will","be","ignored",")",".","bbox_to_anchor",":","`",".BboxBase","`","or","pair","of","floats","Specify","any","arbitrary","location","for","the","legend","in","`","bbox_transform","`","coordinates","(","default","Axes","coordinates",")",".","For","example",",","to","put","the","legend","'s","upper","right","hand","corner","in","the","center","of","the","axes","the","following","keywords","can","be","used",":",":","loc='upper","right","'",",","bbox_to_anchor=","(","0.5",",","0.5",")","ncol",":","integer","The","number","of","columns","that","the","legend","has",".","Default","is","1.","prop",":","None","or",":","class",":","`","matplotlib.font_manager.FontProperties","`","or","dict","The","font","properties","of","the","legend",".","If","None","(","default",")",",","the","current",":","data",":","`","matplotlib.rcParams","`","will","be","used",".","fontsize",":","int","or","float","or","{","'xx-small","'",",","'","x-small","'",",","'small","'",",","'medium","'",",","'large","'",",","'","x-large","'",",","'xx-large","'","}","Controls","the","font","size","of","the","legend",".","If","the","value","is","numeric","the","size","will","be","the","absolute","font","size","in","points",".","String","values","are","relative","to","the","current","default","font","size",".","This","argument","is","only","used","if","`","prop","`","is","not","specified",".","numpoints",":","None","or","int","The","number","of","marker","points","in","the","legend","when","creating","a","legend","entry","for","a","`",".Line2D","`","(","line",")",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.numpoints","`",".","scatterpoints",":","None","or","int","The","number","of","marker","points","in","the","legend","when","creating","a","legend","entry","for","a","`",".PathCollection","`","(","scatter","plot",")",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.scatterpoints","`",".","scatteryoffsets",":","iterable","of","floats","The","vertical","offset","(","relative","to","the","font","size",")","for","the","markers","created","for","a","scatter","plot","legend","entry",".","0.0","is","at","the","base","the","legend","text",",","and","1.0","is","at","the","top",".","To","draw","all","markers","at","the","same","height",",","set","to","``","[","0.5","]","``",".","Default","is","``","[","0.375",",","0.5",",","0.3125","]","``",".","markerscale",":","None","or","int","or","float","The","relative","size","of","legend","markers","compared","with","the","originally","drawn","ones",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.markerscale","`",".","markerfirst",":","bool","If","*","True","*",",","legend","marker","is","placed","to","the","left","of","the","legend","label",".","If","*","False","*",",","legend","marker","is","placed","to","the","right","of","the","legend","label",".","Default","is","*","True","*",".","frameon",":","None","or","bool","Control","whether","the","legend","should","be","drawn","on","a","patch","(","frame",")",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.frameon","`",".","fancybox",":","None","or","bool","Control","whether","round","edges","should","be","enabled","around","the",":","class",":","`","~matplotlib.patches.FancyBboxPatch","`","which","makes","up","the","legend","'s","background",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.fancybox","`",".","shadow",":","None","or","bool","Control","whether","to","draw","a","shadow","behind","the","legend",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.shadow","`",".","framealpha",":","None","or","float","Control","the","alpha","transparency","of","the","legend","'s","background",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.framealpha","`",".","If","shadow","is","activated","and","*","framealpha","*","is","``","None","``",",","the","default","value","is","ignored",".","facecolor",":","None","or","``","inherit","''","or","a","color","spec","Control","the","legend","'s","background","color",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.facecolor","`",".","If","``","``","inherit","''","``",",","it","will","take",":","rc",":","`","axes.facecolor","`",".","edgecolor",":","None","or","``","inherit","''","or","a","color","spec","Control","the","legend","'s","background","patch","edge","color",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.edgecolor","`","If","``","``","inherit","''","``",",","it","will","take",":","rc",":","`","axes.edgecolor","`",".","mode",":","{","``","expand","''",",","None","}","If","`","mode","`","is","set","to","``","``","expand","''","``","the","legend","will","be","horizontally","expanded","to","fill","the","axes","area","(","or","`","bbox_to_anchor","`","if","defines","the","legend","'s","size",")",".","bbox_transform",":","None","or",":","class",":","`","matplotlib.transforms.Transform","`","The","transform","for","the","bounding","box","(","`","bbox_to_anchor","`",")",".","For","a","value","of","``","None","``","(","default",")","the","Axes'",":","data",":","`","~matplotlib.axes.Axes.transAxes","`","transform","will","be","used",".","title",":","str","or","None","The","legend","'s","title",".","Default","is","no","title","(","``","None","``",")",".","borderpad",":","float","or","None","The","fractional","whitespace","inside","the","legend","border",".","Measured","in","font-size","units",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.borderpad","`",".","labelspacing",":","float","or","None","The","vertical","space","between","the","legend","entries",".","Measured","in","font-size","units",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.labelspacing","`",".","handlelength",":","float","or","None","The","length","of","the","legend","handles",".","Measured","in","font-size","units",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.handlelength","`",".","handletextpad",":","float","or","None","The","pad","between","the","legend","handle","and","text",".","Measured","in","font-size","units",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.handletextpad","`",".","borderaxespad",":","float","or","None","The","pad","between","the","axes","and","legend","border",".","Measured","in","font-size","units",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.borderaxespad","`",".","columnspacing",":","float","or","None","The","spacing","between","columns",".","Measured","in","font-size","units",".","Default","is","``","None","``",",","which","will","take","the","value","from",":","rc",":","`","legend.columnspacing","`",".","handler_map",":","dict","or","None","The","custom","dictionary","mapping","instances","or","types","to","a","legend","handler",".","This","`","handler_map","`","updates","the","default","handler","map","found","at",":","func",":","`","matplotlib.legend.Legend.get_legend_handler_map","`",".","Notes","--","--","-","Users","can","specify","any","arbitrary","location","for","the","legend","using","the","*","bbox_to_anchor","*","keyword","argument",".","bbox_to_anchor","can","be","an","instance","of","BboxBase","(","or","its","derivatives",")","or","a","tuple","of","2","or","4","floats",".","See",":","meth",":","`","set_bbox_to_anchor","`","for","more","detail",".","The","legend","location","can","be","specified","by","setting","*","loc","*","with","a","tuple","of","2","floats",",","which","is","interpreted","as","the","lower-left","corner","of","the","legend","in","the","normalized","axes","coordinate","."]
code: def __init__(
      self,
      parent,
      handles,
      labels,
      loc=None,
      numpoints=None,  # the number of points in the legend line
      markerscale=None,  # the relative size of legend markers
      # vs. original
      markerfirst=True,  # controls ordering (left-to-right) of
      # legend marker and label
      scatterpoints=None,  # number of scatter points
      scatteryoffsets=None,
      prop=None,  # properties for the legend texts
      fontsize=None,  # keyword to set font size directly
      # spacing & pad defined as a fraction of the font-size
      borderpad=None,  # the whitespace inside the legend border
      labelspacing=None,  # the vertical space between the legend
      # entries
      handlelength=None,  # the length of the legend handles
      handleheight=None,  # the height of the legend handles
      handletextpad=None,  # the pad between the legend handle
      # and text
      borderaxespad=None,  # the pad between the axes and legend
      # border
      columnspacing=None,  # spacing between columns
      ncol=1,  # number of columns
      mode=None,  # mode for horizontal distribution of columns.
      # None, "expand"
      fancybox=None,  # True use a fancy box, false use a rounded
      # box, none use rc
      shadow=None,
      title=None,  # set a title for the legend
      framealpha=None,  # set frame alpha
      edgecolor=None,  # frame patch edgecolor
      facecolor=None,  # frame patch facecolor
      bbox_to_anchor=None,  # bbox that the legend will be anchored.
      bbox_transform=None,  # transform for the bbox
      frameon=None,  # draw frame
      handler_map=None,
  ):
      """
  
          Parameters
          ----------
          parent : `~matplotlib.axes.Axes` or `.Figure`
              The artist that contains the legend.
  
          handles : sequence of `.Artist`
              A list of Artists (lines, patches) to be added to the legend.
  
          labels : sequence of strings
              A list of labels to show next to the artists. The length of handles
              and labels should be the same. If they are not, they are truncated
              to the smaller of both lengths.
  
          Other Parameters
          ----------------
  
          loc : int or string or pair of floats, default: 'upper right'
              The location of the legend. Possible codes are:
  
                  ===============   =============
                  Location String   Location Code
                  ===============   =============
                  'best'            0
                  'upper right'     1
                  'upper left'      2
                  'lower left'      3
                  'lower right'     4
                  'right'           5
                  'center left'     6
                  'center right'    7
                  'lower center'    8
                  'upper center'    9
                  'center'          10
                  ===============   =============
  
  
              Alternatively can be a 2-tuple giving ``x, y`` of the lower-left
              corner of the legend in axes coordinates (in which case
              ``bbox_to_anchor`` will be ignored).
  
          bbox_to_anchor : `.BboxBase` or pair of floats
              Specify any arbitrary location for the legend in `bbox_transform`
              coordinates (default Axes coordinates).
  
              For example, to put the legend's upper right hand corner in the
              center of the axes the following keywords can be used::
  
                 loc='upper right', bbox_to_anchor=(0.5, 0.5)
  
          ncol : integer
              The number of columns that the legend has. Default is 1.
  
          prop : None or :class:`matplotlib.font_manager.FontProperties` or dict
              The font properties of the legend. If None (default), the current
              :data:`matplotlib.rcParams` will be used.
  
          fontsize : int or float or {'xx-small', 'x-small', 'small', 'medium', \
  'large', 'x-large', 'xx-large'}
              Controls the font size of the legend. If the value is numeric the
              size will be the absolute font size in points. String values are
              relative to the current default font size. This argument is only
              used if `prop` is not specified.
  
          numpoints : None or int
              The number of marker points in the legend when creating a legend
              entry for a `.Line2D` (line).
              Default is ``None``, which will take the value from
              :rc:`legend.numpoints`.
  
          scatterpoints : None or int
              The number of marker points in the legend when creating
              a legend entry for a `.PathCollection` (scatter plot).
              Default is ``None``, which will take the value from
              :rc:`legend.scatterpoints`.
  
          scatteryoffsets : iterable of floats
              The vertical offset (relative to the font size) for the markers
              created for a scatter plot legend entry. 0.0 is at the base the
              legend text, and 1.0 is at the top. To draw all markers at the
              same height, set to ``[0.5]``. Default is ``[0.375, 0.5, 0.3125]``.
  
          markerscale : None or int or float
              The relative size of legend markers compared with the originally
              drawn ones.
              Default is ``None``, which will take the value from
              :rc:`legend.markerscale`.
  
          markerfirst : bool
              If *True*, legend marker is placed to the left of the legend label.
              If *False*, legend marker is placed to the right of the legend
              label.
              Default is *True*.
  
          frameon : None or bool
              Control whether the legend should be drawn on a patch
              (frame).
              Default is ``None``, which will take the value from
              :rc:`legend.frameon`.
  
          fancybox : None or bool
              Control whether round edges should be enabled around the
              :class:`~matplotlib.patches.FancyBboxPatch` which makes up the
              legend's background.
              Default is ``None``, which will take the value from
              :rc:`legend.fancybox`.
  
          shadow : None or bool
              Control whether to draw a shadow behind the legend.
              Default is ``None``, which will take the value from
              :rc:`legend.shadow`.
  
          framealpha : None or float
              Control the alpha transparency of the legend's background.
              Default is ``None``, which will take the value from
              :rc:`legend.framealpha`.  If shadow is activated and
              *framealpha* is ``None``, the default value is ignored.
  
          facecolor : None or "inherit" or a color spec
              Control the legend's background color.
              Default is ``None``, which will take the value from
              :rc:`legend.facecolor`.  If ``"inherit"``, it will take
              :rc:`axes.facecolor`.
  
          edgecolor : None or "inherit" or a color spec
              Control the legend's background patch edge color.
              Default is ``None``, which will take the value from
              :rc:`legend.edgecolor` If ``"inherit"``, it will take
              :rc:`axes.edgecolor`.
  
          mode : {"expand", None}
              If `mode` is set to ``"expand"`` the legend will be horizontally
              expanded to fill the axes area (or `bbox_to_anchor` if defines
              the legend's size).
  
          bbox_transform : None or :class:`matplotlib.transforms.Transform`
              The transform for the bounding box (`bbox_to_anchor`). For a value
              of ``None`` (default) the Axes'
              :data:`~matplotlib.axes.Axes.transAxes` transform will be used.
  
          title : str or None
              The legend's title. Default is no title (``None``).
  
          borderpad : float or None
              The fractional whitespace inside the legend border.
              Measured in font-size units.
              Default is ``None``, which will take the value from
              :rc:`legend.borderpad`.
  
          labelspacing : float or None
              The vertical space between the legend entries.
              Measured in font-size units.
              Default is ``None``, which will take the value from
              :rc:`legend.labelspacing`.
  
          handlelength : float or None
              The length of the legend handles.
              Measured in font-size units.
              Default is ``None``, which will take the value from
              :rc:`legend.handlelength`.
  
          handletextpad : float or None
              The pad between the legend handle and text.
              Measured in font-size units.
              Default is ``None``, which will take the value from
              :rc:`legend.handletextpad`.
  
          borderaxespad : float or None
              The pad between the axes and legend border.
              Measured in font-size units.
              Default is ``None``, which will take the value from
              :rc:`legend.borderaxespad`.
  
          columnspacing : float or None
              The spacing between columns.
              Measured in font-size units.
              Default is ``None``, which will take the value from
              :rc:`legend.columnspacing`.
  
          handler_map : dict or None
              The custom dictionary mapping instances or types to a legend
              handler. This `handler_map` updates the default handler map
              found at :func:`matplotlib.legend.Legend.get_legend_handler_map`.
  
          Notes
          -----
  
          Users can specify any arbitrary location for the legend using the
          *bbox_to_anchor* keyword argument. bbox_to_anchor can be an instance
          of BboxBase(or its derivatives) or a tuple of 2 or 4 floats.
          See :meth:`set_bbox_to_anchor` for more detail.
  
          The legend location can be specified by setting *loc* with a tuple of
          2 floats, which is interpreted as the lower-left corner of the legend
          in the normalized axes coordinate.
          """
      # local import only to avoid circularity
      from matplotlib.axes import Axes
      from matplotlib.figure import Figure
  
      Artist.__init__(self)
  
      if prop is None:
          if fontsize is not None:
              self.prop = FontProperties(size=fontsize)
          else:
              self.prop = FontProperties(
                  size=rcParams["legend.fontsize"]
              )
      elif isinstance(prop, dict):
          self.prop = FontProperties(**prop)
          if "size" not in prop:
              self.prop.set_size(rcParams["legend.fontsize"])
      else:
          self.prop = prop
  
      self._fontsize = self.prop.get_size_in_points()
  
      self.texts = []
      self.legendHandles = []
      self._legend_title_box = None
  
      #: A dictionary with the extra handler mappings for this Legend
      #: instance.
      self._custom_handler_map = handler_map
  
      locals_view = locals()
      for name in [
          "numpoints",
          "markerscale",
          "shadow",
          "columnspacing",
          "scatterpoints",
          "handleheight",
          "borderpad",
          "labelspacing",
          "handlelength",
          "handletextpad",
          "borderaxespad",
      ]:
          if locals_view[name] is None:
              value = rcParams["legend." + name]
          else:
              value = locals_view[name]
          setattr(self, name, value)
      del locals_view
      # trim handles and labels if illegal label...
      _lab, _hand = [], []
      for label, handle in zip(labels, handles):
          if isinstance(label, six.string_types) and label.startswith(
              "_"
          ):
              warnings.warn(
                  "The handle {!r} has a label of {!r} which "
                  "cannot be automatically added to the "
                  "legend.".format(handle, label)
              )
          else:
              _lab.append(label)
              _hand.append(handle)
      labels, handles = _lab, _hand
  
      handles = list(handles)
      if len(handles) < 2:
          ncol = 1
      self._ncol = ncol
  
      if self.numpoints <= 0:
          raise ValueError(
              "numpoints must be > 0; it was %d" % numpoints
          )
  
      # introduce y-offset for handles of the scatter plot
      if scatteryoffsets is None:
          self._scatteryoffsets = np.array(
              [3.0 / 8.0, 4.0 / 8.0, 2.5 / 8.0]
          )
      else:
          self._scatteryoffsets = np.asarray(scatteryoffsets)
      reps = self.scatterpoints // len(self._scatteryoffsets) + 1
      self._scatteryoffsets = np.tile(self._scatteryoffsets, reps)[
          : self.scatterpoints
      ]
  
      # _legend_box is an OffsetBox instance that contains all
      # legend items and will be initialized from _init_legend_box()
      # method.
      self._legend_box = None
  
      if isinstance(parent, Axes):
          self.isaxes = True
          self.axes = parent
          self.set_figure(parent.figure)
      elif isinstance(parent, Figure):
          self.isaxes = False
          self.set_figure(parent)
      else:
          raise TypeError(
              "Legend needs either Axes or Figure as parent"
          )
      self.parent = parent
  
      if loc is None:
          loc = rcParams["legend.loc"]
          if not self.isaxes and loc in [0, "best"]:
              loc = "upper right"
      if isinstance(loc, six.string_types):
          if loc not in self.codes:
              if self.isaxes:
                  warnings.warn(
                      'Unrecognized location "%s". Falling back '
                      'on "best"; valid locations are\n\t%s\n'
                      % (loc, "\n\t".join(self.codes))
                  )
                  loc = 0
              else:
                  warnings.warn(
                      'Unrecognized location "%s". Falling back '
                      'on "upper right"; '
                      "valid locations are\n\t%s\n"
                      % (loc, "\n\t".join(self.codes))
                  )
                  loc = 1
          else:
              loc = self.codes[loc]
      if not self.isaxes and loc == 0:
          warnings.warn(
              'Automatic legend placement (loc="best") not '
              "implemented for figure legend. "
              'Falling back on "upper right".'
          )
          loc = 1
  
      self._mode = mode
      self.set_bbox_to_anchor(bbox_to_anchor, bbox_transform)
  
      # We use FancyBboxPatch to draw a legend frame. The location
      # and size of the box will be updated during the drawing time.
  
      if facecolor is None:
          facecolor = rcParams["legend.facecolor"]
      if facecolor == "inherit":
          facecolor = rcParams["axes.facecolor"]
  
      if edgecolor is None:
          edgecolor = rcParams["legend.edgecolor"]
      if edgecolor == "inherit":
          edgecolor = rcParams["axes.edgecolor"]
  
      self.legendPatch = FancyBboxPatch(
          xy=(0.0, 0.0),
          width=1.0,
          height=1.0,
          facecolor=facecolor,
          edgecolor=edgecolor,
          mutation_scale=self._fontsize,
          snap=True,
      )
  
      # The width and height of the legendPatch will be set (in the
      # draw()) to the length that includes the padding. Thus we set
      # pad=0 here.
      if fancybox is None:
          fancybox = rcParams["legend.fancybox"]
  
      if fancybox:
          self.legendPatch.set_boxstyle(
              "round", pad=0, rounding_size=0.2
          )
      else:
          self.legendPatch.set_boxstyle("square", pad=0)
  
      self._set_artist_props(self.legendPatch)
  
      self._drawFrame = frameon
      if frameon is None:
          self._drawFrame = rcParams["legend.frameon"]
  
      # init with null renderer
      self._init_legend_box(handles, labels, markerfirst)
  
      # If shadow is activated use framealpha if not
      # explicitly passed. See Issue 8943
      if framealpha is None:
          if shadow:
              self.get_frame().set_alpha(1)
          else:
              self.get_frame().set_alpha(rcParams["legend.framealpha"])
      else:
          self.get_frame().set_alpha(framealpha)
  
      self._loc = loc
      self.set_title(title)
      self._last_fontsize_points = self._fontsize
      self._draggable = None
  
imports: from __future__ import absolute_import, division, print_function, unicode_literals
  import six
  import logging
  import warnings
  import numpy
  from matplotlib import rcParams
  from matplotlib import docstring
  from matplotlib.artist import Artist, allow_rasterization
  from matplotlib.cbook import silent_list, is_hashable
  import matplotlib.colors
  from matplotlib.font_manager import FontProperties
  from matplotlib.lines import Line2D
  from matplotlib.patches import Patch, Rectangle, Shadow, FancyBboxPatch
  from matplotlib.collections import LineCollection, RegularPolyCollection, CircleCollection, PathCollection, PolyCollection
  from matplotlib.transforms import Bbox, BboxBase, TransformedBbox
  from matplotlib.transforms import BboxTransformTo, BboxTransformFrom
  from matplotlib.offsetbox import HPacker, VPacker, TextArea, DrawingArea
  from matplotlib.offsetbox import DraggableOffsetBox
  from matplotlib.container import ErrorbarContainer, BarContainer, StemContainer
  from .None import legend_handler
label_desc: Use image node_id 2 to create a new Legend object from inherited base classes: Artist with example: obj = Legend(parent, handles, labels, loc, numpoints, markerscale, markerfirst, scatterpoints, scatteryoffsets, prop, fontsize, borderpad, labelspacing, handlelength, handleheight, handletextpad, borderaxespad, columnspacing, ncol, mode, fancybox, shadow, title, framealpha, edgecolor, facecolor, bbox_to_anchor, bbox_transform, frameon, handler_map)