class_docstr: A timezone that has a variable offset from UTC
  
  The offset might change if daylight saving time comes into effect,
  or at a point in history when the region decides to change their
  timezone definition.
class_docstr_tok: ["A","timezone","that","has","a","variable","offset","from","UTC","The","offset","might","change","if","daylight","saving","time","comes","into","effect",",","or","at","a","point","in","history","when","the","region","decides","to","change","their","timezone","definition","."]
docstr: 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 saving 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 saving time
  
  >>> try:
  ...     loc_dt1 = amdam.localize(dt, is_dst=None)
  ... except AmbiguousTimeError:
  ...     print('Ambiguous')
  Ambiguous
  
  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 saving 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.
  
  >>> try:
  ...     loc_dt1 = pacific.localize(dt, is_dst=None)
  ... except NonExistentTimeError:
  ...     print('Non-existent')
  Non-existent
docstr_tok: ["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","saving","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","saving","time",">",">",">","try",":","...","loc_dt1","=","amdam.localize","(","dt",",","is_dst=None",")","...","except","AmbiguousTimeError",":","...","print","(","'Ambiguous","'",")","Ambiguous","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","saving","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",".",">",">",">","try",":","...","loc_dt1","=","pacific.localize","(","dt",",","is_dst=None",")","...","except","NonExistentTimeError",":","...","print","(","'Non-existent","'",")","Non-existent"]
code: 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 saving 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 saving time
  
      >>> try:
      ...     loc_dt1 = amdam.localize(dt, is_dst=None)
      ... except AmbiguousTimeError:
      ...     print('Ambiguous')
      Ambiguous
  
      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 saving 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.
  
      >>> try:
      ...     loc_dt1 = pacific.localize(dt, is_dst=None)
      ... except NonExistentTimeError:
      ...     print('Non-existent')
      Non-existent
      """
      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 occurring 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 if is_dst=True
      # Choose the latest (by UTC) applicable timezone if is_dst=False
      # i.e., behave like end-of-DST transition
      dates = {}  # utc -> local
      for local_dt in filtered_possible_loc_dt:
          utc_time = (
              local_dt.replace(tzinfo=None) - local_dt.tzinfo._utcoffset
          )
          assert utc_time not in dates
          dates[utc_time] = local_dt
      return dates[[min, max][not is_dst](dates)]
  
imports: from datetime import datetime, timedelta, tzinfo
  from bisect import bisect_right
  import pytz
  from pytz.exceptions import AmbiguousTimeError, NonExistentTimeError
label_desc: Use image node_id 4 for calling the DstTzInfo obj's underlying member method code with example usage: obj.localize(dt, is_dst) and returns: dates, possible_loc_dt, filtered_possible_loc_dt, unknown, unknown