Add whatsnew, more docs

doc/source/whatsnew/v3.0.0.rst

@@ -75,12 +75,44 @@ Optional libraries below the lowest tested version may still work, but are not c
 +-----------------+---------------------+
 | Package | New Minimum Version |
 +=================+=====================+
-|  |  |
+| pytz | 2023.3 |
 +-----------------+---------------------+
 
 See :ref:`install.dependencies` and :ref:`install.optional_dependencies` for more.
 
-.. _whatsnew_300.api_breaking.other:
+.. _whatsnew_300.api_breaking.pytz:
+
+``pytz`` now an optional dependency
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+pandas now uses :py:mod:`zoneinfo` from the standard library as the default timezone implementation when passing a timezone
+string to various methods. (:issue:`34916`)
+
+*Old behavior:*
+
+.. code-block:: ipython
+
+ In [1]: ts = pd.Timestamp(2024, 1, 1).tz_localize("US/Pacific")
+ In [2]: ts.tz
+ <DstTzInfo 'US/Pacific' LMT-1 day, 16:07:00 STD>
+
+*New behavior:*
+
+.. ipython:: python
+
+ ts = pd.Timestamp(2024, 1, 1).tz_localize("US/Pacific")
+ tz.tz
+
+
+``pytz`` timezone objects are still supported when passed directly, but they will no longer be returned by default
+from string inputs. Moreover, ``pytz`` is no longer a required dependency of pandas, but can be installed
+with the pip extra ``pip install pandas[timezone]``.
+
+
+Additionally, pandas no longer throws ``pytz`` exceptions for timezone operations leading to ambiguous or nonexistent
+times. These operations will now yield :class:`errors.AmbiguousTimeError` and :class:`errors.NonexistentError`
+and are accessible from :mod:`errors`.
+
 
 Other API changes
 ^^^^^^^^^^^^^^^^^

pandas/_libs/tslibs/nattype.pyx

@@ -793,7 +793,7 @@ class NaTType(_NaT):
 
  Parameters
  ----------
- tz : str, pytz.timezone, dateutil.tz.tzfile or None
+ tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None
  Time zone for time which Timestamp will be converted to.
  None will remove timezone holding UTC time.
 
@@ -839,7 +839,7 @@ class NaTType(_NaT):
  ----------
  ordinal : int
  Date corresponding to a proleptic Gregorian ordinal.
- tz : str, pytz.timezone, dateutil.tz.tzfile or None
+ tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None
  Time zone for the Timestamp.
 
  Notes
@@ -1198,7 +1198,7 @@ timedelta}, default 'raise'
 
  Parameters
  ----------
- tz : str, pytz.timezone, dateutil.tz.tzfile or None
+ tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None
  Time zone for time which Timestamp will be converted to.
  None will remove timezone holding UTC time.
 
@@ -1245,7 +1245,7 @@ timedelta}, default 'raise'
 
  Parameters
  ----------
- tz : str, pytz.timezone, dateutil.tz.tzfile or None
+ tz : str, zoneinfo.ZoneInfo, , dateutil.tz.tzfile or None
  Time zone for time which Timestamp will be converted to.
  None will remove timezone holding local time.
 

pandas/_libs/tslibs/timestamps.pyx

@@ -1281,7 +1281,7 @@ class Timestamp(_Timestamp):
  hour, minute, second, microsecond : int, optional, default 0
  tzinfo : datetime.tzinfo, optional, default None
  nanosecond : int, optional, default 0
- tz : str, pytz.timezone, dateutil.tz.tzfile or None
+ tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None
  Time zone for time which Timestamp will have.
  unit : str
  Unit used for conversion if ts_input is of type int or float. The
@@ -1343,7 +1343,7 @@ class Timestamp(_Timestamp):
  ----------
  ordinal : int
  Date corresponding to a proleptic Gregorian ordinal.
- tz : str, pytz.timezone, dateutil.tz.tzfile or None
+ tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None
  Time zone for the Timestamp.
 
  Notes
@@ -2223,7 +2223,7 @@ timedelta}, default 'raise'
 
  Parameters
  ----------
- tz : str, pytz.timezone, dateutil.tz.tzfile or None
+ tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None
  Time zone for time which Timestamp will be converted to.
  None will remove timezone holding local time.
 
@@ -2325,7 +2325,7 @@ default 'raise'
 
  Parameters
  ----------
- tz : str, pytz.timezone, dateutil.tz.tzfile or None
+ tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None
  Time zone for time which Timestamp will be converted to.
  None will remove timezone holding UTC time.