class_docstr: Namespace for datetime related expressions.
docstr: Replace time zone for an expression of type Datetime.
  
  Different from `convert_time_zone`, this will also modify
  the underlying timestamp and will ignore the original time zone.
  
  Parameters
  ----------
  time_zone
      Time zone for the `Datetime` expression. Pass `None` to unset time zone.
  use_earliest
      Determine how to deal with ambiguous datetimes:
  
      - `None` (default): raise
      - `True`: use the earliest datetime
      - `False`: use the latest datetime
  
      .. deprecated:: 0.19.0
          Use `ambiguous` instead
  ambiguous
      Determine how to deal with ambiguous datetimes:
  
      - `'raise'` (default): raise
      - `'earliest'`: use the earliest datetime
      - `'latest'`: use the latest datetime
  
  Examples
  --------
  >>> from datetime import datetime
  >>> df = pl.DataFrame(
  ...     {
  ...         "london_timezone": pl.datetime_range(
  ...             datetime(2020, 3, 1),
  ...             datetime(2020, 7, 1),
  ...             "1mo",
  ...             time_zone="UTC",
  ...             eager=True,
  ...         ).dt.convert_time_zone(time_zone="Europe/London"),
  ...     }
  ... )
  >>> df.select(
  ...     [
  ...         pl.col("london_timezone"),
  ...         pl.col("london_timezone")
  ...         .dt.replace_time_zone(time_zone="Europe/Amsterdam")
  ...         .alias("London_to_Amsterdam"),
  ...     ]
  ... )
  shape: (5, 2)
  ┌─────────────────────────────┬────────────────────────────────┐
  │ london_timezone             ┆ London_to_Amsterdam            │
  │ ---                         ┆ ---                            │
  │ datetime[μs, Europe/London] ┆ datetime[μs, Europe/Amsterdam] │
  ╞═════════════════════════════╪════════════════════════════════╡
  │ 2020-03-01 00:00:00 GMT     ┆ 2020-03-01 00:00:00 CET        │
  │ 2020-04-01 01:00:00 BST     ┆ 2020-04-01 01:00:00 CEST       │
  │ 2020-05-01 01:00:00 BST     ┆ 2020-05-01 01:00:00 CEST       │
  │ 2020-06-01 01:00:00 BST     ┆ 2020-06-01 01:00:00 CEST       │
  │ 2020-07-01 01:00:00 BST     ┆ 2020-07-01 01:00:00 CEST       │
  └─────────────────────────────┴────────────────────────────────┘
  
  You can use `use_earliest` to deal with ambiguous datetimes:
  
  >>> dates = [
  ...     "2018-10-28 01:30",
  ...     "2018-10-28 02:00",
  ...     "2018-10-28 02:30",
  ...     "2018-10-28 02:00",
  ... ]
  >>> df = pl.DataFrame(
  ...     {
  ...         "ts": pl.Series(dates).str.strptime(pl.Datetime),
  ...         "ambiguous": ["earliest", "earliest", "latest", "latest"],
  ...     }
  ... )
  >>> df.with_columns(
  ...     ts_localized=pl.col("ts").dt.replace_time_zone(
  ...         "Europe/Brussels", ambiguous=pl.col("ambiguous")
  ...     )
  ... )
  shape: (4, 3)
  ┌─────────────────────┬───────────┬───────────────────────────────┐
  │ ts                  ┆ ambiguous ┆ ts_localized                  │
  │ ---                 ┆ ---       ┆ ---                           │
  │ datetime[μs]        ┆ str       ┆ datetime[μs, Europe/Brussels] │
  ╞═════════════════════╪═══════════╪═══════════════════════════════╡
  │ 2018-10-28 01:30:00 ┆ earliest  ┆ 2018-10-28 01:30:00 CEST      │
  │ 2018-10-28 02:00:00 ┆ earliest  ┆ 2018-10-28 02:00:00 CEST      │
  │ 2018-10-28 02:30:00 ┆ latest    ┆ 2018-10-28 02:30:00 CET       │
  │ 2018-10-28 02:00:00 ┆ latest    ┆ 2018-10-28 02:00:00 CET       │
  └─────────────────────┴───────────┴───────────────────────────────┘
docstr_tok: ["Replace","time","zone","for","an","expression","of","type","Datetime",".","Different","from","`","convert_time_zone","`",",","this","will","also","modify","the","underlying","timestamp","and","will","ignore","the","original","time","zone",".","Parameters","--","--","--","--","--","time_zone","Time","zone","for","the","`","Datetime","`","expression",".","Pass","`","None","`","to","unset","time","zone",".","use_earliest","Determine","how","to","deal","with","ambiguous","datetimes",":","-","`","None","`","(","default",")",":","raise","-","`","True","`",":","use","the","earliest","datetime","-","`","False","`",":","use","the","latest","datetime","..","deprecated",":",":","0.19.0","Use","`","ambiguous","`","instead","ambiguous","Determine","how","to","deal","with","ambiguous","datetimes",":","-","`","'raise","'","`","(","default",")",":","raise","-","`","'earliest","'","`",":","use","the","earliest","datetime","-","`","'latest","'","`",":","use","the","latest","datetime","Examples","--","--","--","--",">",">",">","from","datetime","import","datetime",">",">",">","df","=","pl.DataFrame","(","...","{","...","``","london_timezone","''",":","pl.datetime_range","(","...","datetime","(","2020",",","3",",","1",")",",","...","datetime","(","2020",",","7",",","1",")",",","...","``","1mo","''",",","...","time_zone=","''","UTC","''",",","...","eager=True",",","...",")",".dt.convert_time_zone","(","time_zone=","''","Europe\/London","''",")",",","...","}","...",")",">",">",">","df.select","(","...","[","...","pl.col","(","``","london_timezone","''",")",",","...","pl.col","(","``","london_timezone","''",")","...",".dt.replace_time_zone","(","time_zone=","''","Europe\/Amsterdam","''",")","...",".alias","(","``","London_to_Amsterdam","''",")",",","...","]","...",")","shape",":","(","5",",","2",")","\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510","\u2502","london_timezone","\u2506","London_to_Amsterdam","\u2502","\u2502","--","-","\u2506","--","-","\u2502","\u2502","datetime","[","\u03bcs",",","Europe\/London","]","\u2506","datetime","[","\u03bcs",",","Europe\/Amsterdam","]","\u2502","\u255e\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561","\u2502","2020-03-01","00:00:00","GMT","\u2506","2020-03-01","00:00:00","CET","\u2502","\u2502","2020-04-01","01:00:00","BST","\u2506","2020-04-01","01:00:00","CEST","\u2502","\u2502","2020-05-01","01:00:00","BST","\u2506","2020-05-01","01:00:00","CEST","\u2502","\u2502","2020-06-01","01:00:00","BST","\u2506","2020-06-01","01:00:00","CEST","\u2502","\u2502","2020-07-01","01:00:00","BST","\u2506","2020-07-01","01:00:00","CEST","\u2502","\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518","You","can","use","`","use_earliest","`","to","deal","with","ambiguous","datetimes",":",">",">",">","dates","=","[","...","``","2018-10-28","01:30","''",",","...","``","2018-10-28","02:00","''",",","...","``","2018-10-28","02:30","''",",","...","``","2018-10-28","02:00","''",",","...","]",">",">",">","df","=","pl.DataFrame","(","...","{","...","``","ts","''",":","pl.Series","(","dates",")",".str.strptime","(","pl.Datetime",")",",","...","``","ambiguous","''",":","[","``","earliest","''",",","``","earliest","''",",","``","latest","''",",","``","latest","''","]",",","...","}","...",")",">",">",">","df.with_columns","(","...","ts_localized=pl.col","(","``","ts","''",")",".dt.replace_time_zone","(","...","``","Europe\/Brussels","''",",","ambiguous=pl.col","(","``","ambiguous","''",")","...",")","...",")","shape",":","(","4",",","3",")","\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510","\u2502","ts","\u2506","ambiguous","\u2506","ts_localized","\u2502","\u2502","--","-","\u2506","--","-","\u2506","--","-","\u2502","\u2502","datetime","[","\u03bcs","]","\u2506","str","\u2506","datetime","[","\u03bcs",",","Europe\/Brussels","]","\u2502","\u255e\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561","\u2502","2018-10-28","01:30:00","\u2506","earliest","\u2506","2018-10-28","01:30:00","CEST","\u2502","\u2502","2018-10-28","02:00:00","\u2506","earliest","\u2506","2018-10-28","02:00:00","CEST","\u2502","\u2502","2018-10-28","02:30:00","\u2506","latest","\u2506","2018-10-28","02:30:00","CET","\u2502","\u2502","2018-10-28","02:00:00","\u2506","latest","\u2506","2018-10-28","02:00:00","CET","\u2502","\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518"]
code: def replace_time_zone(
      self,
      time_zone: str | None,
      *,
      use_earliest: bool | None = None,
      ambiguous: Ambiguous | Expr = "raise",
  ) -> Expr:
      """
      Replace time zone for an expression of type Datetime.
  
      Different from `convert_time_zone`, this will also modify
      the underlying timestamp and will ignore the original time zone.
  
      Parameters
      ----------
      time_zone
          Time zone for the `Datetime` expression. Pass `None` to unset time zone.
      use_earliest
          Determine how to deal with ambiguous datetimes:
  
          - `None` (default): raise
          - `True`: use the earliest datetime
          - `False`: use the latest datetime
  
          .. deprecated:: 0.19.0
              Use `ambiguous` instead
      ambiguous
          Determine how to deal with ambiguous datetimes:
  
          - `'raise'` (default): raise
          - `'earliest'`: use the earliest datetime
          - `'latest'`: use the latest datetime
  
      Examples
      --------
      >>> from datetime import datetime
      >>> df = pl.DataFrame(
      ...     {
      ...         "london_timezone": pl.datetime_range(
      ...             datetime(2020, 3, 1),
      ...             datetime(2020, 7, 1),
      ...             "1mo",
      ...             time_zone="UTC",
      ...             eager=True,
      ...         ).dt.convert_time_zone(time_zone="Europe/London"),
      ...     }
      ... )
      >>> df.select(
      ...     [
      ...         pl.col("london_timezone"),
      ...         pl.col("london_timezone")
      ...         .dt.replace_time_zone(time_zone="Europe/Amsterdam")
      ...         .alias("London_to_Amsterdam"),
      ...     ]
      ... )
      shape: (5, 2)
      ┌─────────────────────────────┬────────────────────────────────┐
      │ london_timezone             ┆ London_to_Amsterdam            │
      │ ---                         ┆ ---                            │
      │ datetime[μs, Europe/London] ┆ datetime[μs, Europe/Amsterdam] │
      ╞═════════════════════════════╪════════════════════════════════╡
      │ 2020-03-01 00:00:00 GMT     ┆ 2020-03-01 00:00:00 CET        │
      │ 2020-04-01 01:00:00 BST     ┆ 2020-04-01 01:00:00 CEST       │
      │ 2020-05-01 01:00:00 BST     ┆ 2020-05-01 01:00:00 CEST       │
      │ 2020-06-01 01:00:00 BST     ┆ 2020-06-01 01:00:00 CEST       │
      │ 2020-07-01 01:00:00 BST     ┆ 2020-07-01 01:00:00 CEST       │
      └─────────────────────────────┴────────────────────────────────┘
  
      You can use `use_earliest` to deal with ambiguous datetimes:
  
      >>> dates = [
      ...     "2018-10-28 01:30",
      ...     "2018-10-28 02:00",
      ...     "2018-10-28 02:30",
      ...     "2018-10-28 02:00",
      ... ]
      >>> df = pl.DataFrame(
      ...     {
      ...         "ts": pl.Series(dates).str.strptime(pl.Datetime),
      ...         "ambiguous": ["earliest", "earliest", "latest", "latest"],
      ...     }
      ... )
      >>> df.with_columns(
      ...     ts_localized=pl.col("ts").dt.replace_time_zone(
      ...         "Europe/Brussels", ambiguous=pl.col("ambiguous")
      ...     )
      ... )
      shape: (4, 3)
      ┌─────────────────────┬───────────┬───────────────────────────────┐
      │ ts                  ┆ ambiguous ┆ ts_localized                  │
      │ ---                 ┆ ---       ┆ ---                           │
      │ datetime[μs]        ┆ str       ┆ datetime[μs, Europe/Brussels] │
      ╞═════════════════════╪═══════════╪═══════════════════════════════╡
      │ 2018-10-28 01:30:00 ┆ earliest  ┆ 2018-10-28 01:30:00 CEST      │
      │ 2018-10-28 02:00:00 ┆ earliest  ┆ 2018-10-28 02:00:00 CEST      │
      │ 2018-10-28 02:30:00 ┆ latest    ┆ 2018-10-28 02:30:00 CET       │
      │ 2018-10-28 02:00:00 ┆ latest    ┆ 2018-10-28 02:00:00 CET       │
      └─────────────────────┴───────────┴───────────────────────────────┘
  
      """
      ambiguous = rename_use_earliest_to_ambiguous(
          use_earliest, ambiguous
      )
      if not isinstance(ambiguous, pl.Expr):
          ambiguous = F.lit(ambiguous)
      return wrap_expr(
          self._pyexpr.dt_replace_time_zone(
              time_zone, ambiguous._pyexpr
          )
      )
  
imports: from __future__ import annotations
  import datetime
  from typing import TYPE_CHECKING
  import polars._reexport
  from polars import functions
  from polars.datatypes import DTYPE_TEMPORAL_UNITS, Date, Int32
  from polars.utils._parse_expr_input import parse_as_expression
  from polars.utils._wrap import wrap_expr
  from polars.utils.convert import _timedelta_to_pl_duration
  from polars.utils.deprecation import deprecate_renamed_function, deprecate_saturating, issue_deprecation_warning, rename_use_earliest_to_ambiguous
label_desc: Use image node_id 30 for calling the ExprDateTimeNameSpace obj's underlying member method code with example usage: obj.replace_time_zone(time_zone) and returns: wrap_expr