docs: def localize(self, dt, is_dst=False):
          '''Convert naive time to local time.
  
          This method should be used to construct localtimes, rather
          than passing a tzinfo argument to a datetime constructor.
  
          is_dst is used to determine the correct timezone in the ambigous
          period at the end of daylight savings time.
  
          >>> from pytz import timezone
          >>> fmt = '%Y-%m-%d %H:%M:%S %Z (%z)'
          >>> amdam = timezone('Europe/Amsterdam')
          >>> dt  = datetime(2004, 10, 31, 2, 0, 0)
          >>> loc_dt1 = amdam.localize(dt, is_dst=True)
          >>> loc_dt2 = amdam.localize(dt, is_dst=False)
          >>> loc_dt1.strftime(fmt)
          '2004-10-31 02:00:00 CEST (+0200)'
          >>> loc_dt2.strftime(fmt)
          '2004-10-31 02:00:00 CET (+0100)'
          >>> str(loc_dt2 - loc_dt1)
          '1:00:00'
  
          Use is_dst=None to raise an AmbiguousTimeError for ambiguous
          times at the end of daylight savings
  
          >>> loc_dt1 = amdam.localize(dt, is_dst=None)
          Traceback (most recent call last):
              [...]
          AmbiguousTimeError: 2004-10-31 02:00:00
  
          is_dst defaults to False
  
          >>> amdam.localize(dt) == amdam.localize(dt, False)
          True
  
          is_dst is also used to determine the correct timezone in the
          wallclock times jumped over at the start of daylight savings time.
  
          >>> pacific = timezone('US/Pacific')
          >>> dt = datetime(2008, 3, 9, 2, 0, 0)
          >>> ploc_dt1 = pacific.localize(dt, is_dst=True)
          >>> ploc_dt2 = pacific.localize(dt, is_dst=False)
          >>> ploc_dt1.strftime(fmt)
          '2008-03-09 02:00:00 PDT (-0700)'
          >>> ploc_dt2.strftime(fmt)
          '2008-03-09 02:00:00 PST (-0800)'
          >>> str(ploc_dt2 - ploc_dt1)
          '1:00:00'
  
          Use is_dst=None to raise a NonExistentTimeError for these skipped
          times.
  
          >>> loc_dt1 = pacific.localize(dt, is_dst=None)
          Traceback (most recent call last):
              [...]
          NonExistentTimeError: 2008-03-09 02:00:00
          '''
          if dt.tzinfo is not None:
              raise ValueError, 'Not naive datetime (tzinfo is already set)'
  
          # Find the two best possibilities.
          possible_loc_dt = set()
          for delta in [timedelta(days=-1), timedelta(days=1)]:
              loc_dt = dt + delta
              idx = max(0, bisect_right(
                  self._utc_transition_times, loc_dt) - 1)
              inf = self._transition_info[idx]
              tzinfo = self._tzinfos[inf]
              loc_dt = tzinfo.normalize(dt.replace(tzinfo=tzinfo))
              if loc_dt.replace(tzinfo=None) == dt:
                  possible_loc_dt.add(loc_dt)
  
          if len(possible_loc_dt) == 1:
              return possible_loc_dt.pop()
  
          # If there are no possibly correct timezones, we are attempting
          # to convert a time that never happened - the time period jumped
          # during the start-of-DST transition period.
          if len(possible_loc_dt) == 0:
              # If we refuse to guess, raise an exception.
              if is_dst is None:
                  raise NonExistentTimeError(dt)
  
              # If we are forcing the pre-DST side of the DST transition, we
              # obtain the correct timezone by winding the clock forward a few
              # hours.
              elif is_dst:
                  return self.localize(
                      dt + timedelta(hours=6), is_dst=True) - timedelta(hours=6)
  
              # If we are forcing the post-DST side of the DST transition, we
              # obtain the correct timezone by winding the clock back.
              else:
                  return self.localize(
                      dt - timedelta(hours=6), is_dst=False) + timedelta(hours=6)
  
  
          # If we get this far, we have multiple possible timezones - this
          # is an ambiguous case occuring during the end-of-DST transition.
  
          # If told to be strict, raise an exception since we have an
          # ambiguous case
          if is_dst is None:
              raise AmbiguousTimeError(dt)
  
          # Filter out the possiblilities that don't match the requested
          # is_dst
          filtered_possible_loc_dt = [
              p for p in possible_loc_dt
                  if bool(p.tzinfo._dst) == is_dst
              ]
  
          # Hopefully we only have one possibility left. Return it.
          if len(filtered_possible_loc_dt) == 1:
              return filtered_possible_loc_dt[0]
  
          if len(filtered_possible_loc_dt) == 0:
              filtered_possible_loc_dt = list(possible_loc_dt)
  
          # If we get this far, we have in a wierd timezone transition
          # where the clocks have been wound back but is_dst is the same
          # in both (eg. Europe/Warsaw 1915 when they switched to CET).
          # At this point, we just have to guess unless we allow more
          # hints to be passed in (such as the UTC offset or abbreviation),
          # but that is just getting silly.
          #
          # Choose the earliest (by UTC) applicable timezone.
          def mycmp(a,b):
              return cmp(
                      a.replace(tzinfo=None) - a.tzinfo._utcoffset,
                      b.replace(tzinfo=None) - b.tzinfo._utcoffset,
                      )
          filtered_possible_loc_dt.sort(mycmp)
          return filtered_possible_loc_dt[0]