Simplify tz / utc arguments

Author: MarcoGorelli

pandas/core/arrays/datetimes.py

@@ -2134,7 +2134,7 @@ def objects_to_datetime64ns(
     dayfirst : bool
     yearfirst : bool
     utc : bool, default False
-        Whether to convert timezone-aware timestamps to UTC.
+        Whether to convert/localize timestamps to UTC.
     errors : {'raise', 'ignore', 'coerce'}
     require_iso8601 : bool, default False
     allow_object : bool

pandas/core/tools/datetimes.py

@@ -38,7 +38,6 @@
     AnyArrayLike,
     ArrayLike,
     DateTimeErrorChoices,
-    Timezone,
     npt,
 )
 
@@ -239,7 +238,7 @@ def _maybe_cache(
 
 
 def _box_as_indexlike(
-    dt_array: ArrayLike, utc: bool | None = None, name: Hashable = None
+    dt_array: ArrayLike, utc: bool = False, name: Hashable = None
 ) -> Index:
     """
     Properly boxes the ndarray of datetimes to DatetimeIndex
@@ -249,8 +248,8 @@ def _box_as_indexlike(
     ----------
     dt_array: 1-d array
         Array of datetimes to be wrapped in an Index.
-    tz : object
-        None or 'utc'
+    utc : bool
+        Whether to convert/localize timestamps to UTC.
     name : string, default None
         Name for a resulting index
 
@@ -290,7 +289,7 @@ def _convert_and_box_cache(
     from pandas import Series
 
     result = Series(arg).map(cache_array)
-    return _box_as_indexlike(result._values, utc=None, name=name)
+    return _box_as_indexlike(result._values, utc=False, name=name)
 
 
 def _return_parsed_timezone_results(result: np.ndarray, timezones, tz, name) -> Index:
@@ -326,7 +325,7 @@ def _convert_listlike_datetimes(
     arg,
     format: str | None,
     name: Hashable = None,
-    tz: Timezone | None = None,
+    utc: bool = False,
     unit: str | None = None,
     errors: DateTimeErrorChoices = "raise",
     infer_datetime_format: bool = False,
@@ -344,8 +343,8 @@ def _convert_listlike_datetimes(
         date to be parsed
     name : object
         None or string for the Index name
-    tz : object
-        None or 'utc'
+    utc : bool
+        Whether to convert/localize timestamps to UTC.
     unit : str
         None or string of the frequency of the passed data
     errors : str
@@ -368,10 +367,11 @@ def _convert_listlike_datetimes(
 
     arg_dtype = getattr(arg, "dtype", None)
     # these are shortcutable
+    tz = "utc" if utc else None
     if is_datetime64tz_dtype(arg_dtype):
         if not isinstance(arg, (DatetimeArray, DatetimeIndex)):
             return DatetimeIndex(arg, tz=tz, name=name)
-        if tz == "utc":
+        if utc:
             arg = arg.tz_convert(None).tz_localize(tz)
         return arg
 
@@ -432,7 +432,6 @@ def _convert_listlike_datetimes(
         if res is not None:
             return res
 
-    utc = tz == "utc"
     result, tz_parsed = objects_to_datetime64ns(
         arg,
         dayfirst=dayfirst,
@@ -451,7 +450,6 @@ def _convert_listlike_datetimes(
         dta = DatetimeArray(result, dtype=tz_to_dtype(tz_parsed))
         return DatetimeIndex._simple_new(dta, name=name)
 
-    utc = tz == "utc"
     return _box_as_indexlike(result, utc=utc, name=name)
 
 
@@ -657,7 +655,7 @@ def to_datetime(
     errors: DateTimeErrorChoices = ...,
     dayfirst: bool = ...,
     yearfirst: bool = ...,
-    utc: bool | None = ...,
+    utc: bool = ...,
     format: str | None = ...,
     exact: bool = ...,
     unit: str | None = ...,
@@ -674,7 +672,7 @@ def to_datetime(
     errors: DateTimeErrorChoices = ...,
     dayfirst: bool = ...,
     yearfirst: bool = ...,
-    utc: bool | None = ...,
+    utc: bool = ...,
     format: str | None = ...,
     exact: bool = ...,
     unit: str | None = ...,
@@ -691,7 +689,7 @@ def to_datetime(
     errors: DateTimeErrorChoices = ...,
     dayfirst: bool = ...,
     yearfirst: bool = ...,
-    utc: bool | None = ...,
+    utc: bool = ...,
     format: str | None = ...,
     exact: bool = ...,
     unit: str | None = ...,
@@ -707,7 +705,7 @@ def to_datetime(
     errors: DateTimeErrorChoices = "raise",
     dayfirst: bool = False,
     yearfirst: bool = False,
-    utc: bool | None = None,
+    utc: bool = False,
     format: str | None = None,
     exact: bool = True,
     unit: str | None = None,
@@ -756,7 +754,7 @@ def to_datetime(
             ``yearfirst=True`` is not strict, but will prefer to parse
             with year first.
 
-    utc : bool, default None
+    utc : bool, default False
         Control timezone-related parsing, localization and conversion.
 
         - If :const:`True`, the function *always* returns a timezone-aware
@@ -1049,10 +1047,9 @@ def to_datetime(
     if origin != "unix":
         arg = _adjust_to_origin(arg, origin, unit)
 
-    tz = "utc" if utc else None
     convert_listlike = partial(
         _convert_listlike_datetimes,
-        tz=tz,
+        utc=utc,
         unit=unit,
         dayfirst=dayfirst,
         yearfirst=yearfirst,
@@ -1065,11 +1062,11 @@ def to_datetime(
 
     if isinstance(arg, Timestamp):
         result = arg
-        if tz is not None:
+        if utc:
             if arg.tz is not None:
-                result = arg.tz_convert(tz)
+                result = arg.tz_convert("utc")
             else:
-                result = arg.tz_localize(tz)
+                result = arg.tz_localize("utc")
     elif isinstance(arg, ABCSeries):
         cache_array = _maybe_cache(arg, format, cache, convert_listlike)
         if not cache_array.empty:
@@ -1078,7 +1075,7 @@ def to_datetime(
             values = convert_listlike(arg._values, format)
             result = arg._constructor(values, index=arg.index, name=arg.name)
     elif isinstance(arg, (ABCDataFrame, abc.MutableMapping)):
-        result = _assemble_from_unit_mappings(arg, errors, tz)
+        result = _assemble_from_unit_mappings(arg, errors, utc)
     elif isinstance(arg, Index):
         cache_array = _maybe_cache(arg, format, cache, convert_listlike)
         if not cache_array.empty:
@@ -1145,7 +1142,7 @@ def to_datetime(
 }
 
 
-def _assemble_from_unit_mappings(arg, errors: DateTimeErrorChoices, tz):
+def _assemble_from_unit_mappings(arg, errors: DateTimeErrorChoices, utc: bool):
     """
     assemble the unit specified fields from the arg (DataFrame)
     Return a Series for actual parsing
@@ -1158,7 +1155,8 @@ def _assemble_from_unit_mappings(arg, errors: DateTimeErrorChoices, tz):
         - If :const:`'raise'`, then invalid parsing will raise an exception
         - If :const:`'coerce'`, then invalid parsing will be set as :const:`NaT`
         - If :const:`'ignore'`, then invalid parsing will return the input
-    tz : None or 'utc'
+    utc : bool
+        Whether to convert/localize timestamps to UTC.
 
     Returns
     -------
@@ -1221,7 +1219,7 @@ def coerce(values):
         + coerce(arg[unit_rev["day"]])
     )
     try:
-        values = to_datetime(values, format="%Y%m%d", errors=errors, utc=tz)
+        values = to_datetime(values, format="%Y%m%d", errors=errors, utc=utc)
     except (TypeError, ValueError) as err:
         raise ValueError(f"cannot assemble the datetimes: {err}") from err
 

pandas/io/parsers/base_parser.py

@@ -1115,7 +1115,7 @@ def converter(*date_cols):
             try:
                 return tools.to_datetime(
                     ensure_object(strs),
-                    utc=None,
+                    utc=False,
                     dayfirst=dayfirst,
                     errors="ignore",
                     infer_datetime_format=infer_datetime_format,

pandas/io/sql.py

@@ -91,7 +91,7 @@ def _process_parse_dates_argument(parse_dates):
 
 
 def _handle_date_column(
-    col, utc: bool | None = None, format: str | dict[str, Any] | None = None
+    col, utc: bool = False, format: str | dict[str, Any] | None = None
 ):
     if isinstance(format, dict):
         # GH35185 Allow custom error values in parse_dates argument of