Update timezone content (ProjectPythia#620)

Manually construct a timezone of known offset, and introduce zoneinfo to replace pytz intro. Minor cleanups.

Author: dcamron

core/datetime/datetime.ipynb

@@ -34,7 +34,7 @@
     "1. Introduce the [time](https://docs.python.org/3/library/time.html) and [datetime](https://docs.python.org/3/library/datetime.html) modules from the Python Standard Library\n",
     "1. Look at formatted input and output of dates and times\n",
     "1. See how we can do simple arithmetic on date and time data, by making use of the `timedelta` object\n",
-    "1. Briefly make use of the [pytz](https://pypi.org/project/pytz/) module to handle some thorny time zone issues in Python."
+    "1. Briefly make use of the [`zoneinfo`](https://docs.python.org/3/library/zoneinfo.html) module to handle time zone awareness and conversions in Python."
    ]
   },
   {
@@ -64,7 +64,7 @@
    "source": [
     "## Imports\n",
     "\n",
-    "For the examples on this page, we import three modules from the Python Standard Library, as well as one third-party module.  The import syntax used here, as well as a discussion on this syntax and an overview of these modules, can be found in the next section."
+    "For the examples on this page, we import three modules from the Python Standard Library.  The import syntax used here, as well as a discussion on this syntax and an overview of these modules, can be found in the next section."
    ]
   },
   {
@@ -76,11 +76,8 @@
     "# Python Standard Library packages\n",
     "# We'll discuss below WHY we alias the packages this way\n",
     "import datetime as dt\n",
-    "import math\n",
     "import time as tm\n",
-    "\n",
-    "# Third-party package for time zone handling, we'll discuss below!\n",
-    "import pytz"
+    "from zoneinfo import ZoneInfo"
    ]
   },
   {
@@ -203,7 +200,7 @@
     "\n",
     "-   performing date and time arithmetic and calculating time duration\n",
     "-   reading and writing date and time strings with various formats\n",
-    "-   handling time zones (with the help of third-party libraries)\n",
+    "-   handling time zones (with the help of the Standard Library's [`zoneinfo`](https://docs.python.org/3/library/zoneinfo.html) module)\n",
     "\n",
     "The `time` and `datetime` modules overlap in functionality, but in your geoscientific work, you will probably be using the `datetime` module more than the `time` module."
    ]
@@ -429,20 +426,29 @@
    "source": [
     "Notice that `aware` has `+00:00` appended at the end, indicating zero hours offset from UTC.\n",
     "\n",
-    "Our `naive` object shows the local time on whatever computer was used to run this code. If you're reading this online, chances are the code was executed on a cloud server that already uses UTC.  If this is the case, `naive` and `aware` will differ only at the microsecond level, due to round-off error.\n",
-    "\n",
-    "In the code above, we used `dt.timezone.utc` to initialize the UTC timezone for our `aware` object. Unfortunately, at this time, the Python Standard Library does not fully support initializing datetime objects with arbitrary time zones; it also does not fully support conversions between time zones for datetime objects.  However, there exist third-party libraries that provide some of this functionality; one such library is covered below."
+    "Our `naive` object shows the local time on whatever computer was used to run this code. If you're reading this online, chances are the code was executed on a cloud server that already uses UTC.  If this is the case, `naive` and `aware` will differ only at the microsecond level, due to round-off error."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Full time zone support with the `pytz` module\n",
-    "\n",
-    "For improved handling of time zones in Python, you will need the third-party [pytz](https://pypi.org/project/pytz/) module, whose classes build upon, or, in object-oriented programming terms, inherit from, classes from the `datetime` module.\n",
+    "````{note}\n",
+    "`datetime` provides an alias to access `datetime.timezone.UTC` that may simplify the above code for you:\n",
+    "```python\n",
+    "from datetime import datetime, UTC\n",
+    "aware = datetime.now(UTC)\n",
+    "```\n",
+    "````"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Fixed UTC Offsets with `datetime.timezone`\n",
     "\n",
-    "In this next example, we repeat the above exercise, but this time, we use a method from the `pytz` module to initialize the `aware` object in a different time zone:"
+    "When you know the exact UTC offset for a time zone and do not need Daylight Saving Time handling, you can construct a time zone directly from the `datetime` module using `datetime.timezone` and a `datetime.timedelta`. This approach requires no external data — the offset is purely arithmetic. For example, let's construct US Mountain Daylight Time (MDT), which is defined as 6 hours behind UTC (UTC-6):"
    ]
   },
   {
@@ -452,22 +458,27 @@
    "outputs": [],
    "source": [
     "naive = dt.datetime.now()\n",
-    "aware = dt.datetime.now(pytz.timezone('US/Mountain'))\n",
-    "print(f\"I am time zone naive: {naive}.\")\n",
-    "print(f\"I am time zone aware: {aware}.\")"
+    "TZ_MDT = dt.timezone(offset=dt.timedelta(hours=-6), name='MDT')\n",
+    "aware = dt.datetime.now(tz=TZ_MDT)\n",
+    "print(f\"I am time zone naive: {naive}. My time zone is {naive.tzname()}.\")\n",
+    "print(f\"I am time zone aware: {aware}. My time zone is {aware.tzname()}.\")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The `pytz.timezone()` method takes a time zone string; if this string is formatted correctly, the method returns a `tzinfo` object, which can be used when making a datetime object time zone aware.  This initializes the time zone for the newly aware object to a specific time zone matching the time zone string. The `-06:00` indicates that we are now operating in a time zone six hours behind UTC.\n",
+    "### Handling Time Zones with `zoneinfo`\n",
     "\n",
-    "### Print Time with a Different Time Zone\n",
+    "Python 3.9 introduced the [`zoneinfo`](https://docs.python.org/3/library/zoneinfo.html) module to the Standard Library, providing access to the [IANA time zone database](https://www.iana.org/time-zones). This allows you to create time zone aware datetime objects using named time zones such as `'US/Mountain'` or `'America/New_York'`, without any third-party packages.\n",
     "\n",
-    "If you have data that are in UTC, and wish to convert them to another time zone (in this example, US Mountain Time Zone), you will again need to make use of the `pytz` module.\n",
+    "A key advantage of IANA time zones over a fixed UTC offset is that they automatically account for Daylight Saving Time (DST). For example, `ZoneInfo('US/Mountain')` will report `MST` (UTC-7) in winter and `MDT` (UTC-6) in summer.\n",
     "\n",
-    "First, we will create a new datetime object with the [utcnow()](https://docs.python.org/3/library/datetime.html#datetime.datetime.utcnow) method.  Despite the name of this method, the newly created object is time zone naive.  Therefore, we must invoke the object's [replace()](https://docs.python.org/3/library/datetime.html#datetime.datetime.replace) method and specify UTC with a `tzinfo` object in order to make the object time zone aware. As described above, we can use the `pytz` module's timezone() method to create a new `tzinfo` object, again using the time zone string 'US/Mountain' (US Mountain Time Zone). To convert the datetime object `utc` from UTC to Mountain Time, we can then run the [astimezone()](https://docs.python.org/3/library/datetime.html#datetime.datetime.astimezone) method."
+    ":::{warning}\n",
+    "`zoneinfo` reads time zone data from the operating system's timezone database. On most Linux and macOS systems this is available automatically. On Windows, or in minimal environments such as some Docker containers, this database may be absent. In those cases, install the [`tzdata`](https://pypi.org/project/tzdata/) package (`pip install tzdata`), which provides the IANA database as a Python package and is used by `zoneinfo` as a fallback.\n",
+    ":::\n",
+    "\n",
+    "In the next example, we create a time zone aware datetime using `ZoneInfo` and inspect the time zone name with `tzname()`:"
    ]
   },
   {
@@ -476,25 +487,41 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "utc = dt.datetime.utcnow().replace(tzinfo=pytz.utc)\n",
-    "print(\"The UTC time is {}.\".format(utc.strftime('%B %d, %Y, %-I:%M%p')))\n",
-    "mountaintz = pytz.timezone(\"US/Mountain\")\n",
-    "ny = utc.astimezone(mountaintz)\n",
-    "print(\"The 'US/Mountain' time is {}.\".format(ny.strftime('%B %d, %Y, %-I:%M%p')))"
+    "naive = dt.datetime.now()\n",
+    "aware = dt.datetime.now(ZoneInfo('US/Mountain'))\n",
+    "print(f\"I am time zone naive: {naive}. My time zone is {naive.tzname()}.\")\n",
+    "print(f\"I am time zone aware: {aware}. My time zone is {aware.tzname()}.\")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In the above example, we also use the `strftime()` method to format the date and time string in a human-friendly format."
+    "The `ZoneInfo` object passed to `datetime.now()` tells Python which IANA time zone to use. The time zone name returned by `tzname()` reflects whether DST is in effect — `MST` in winter, `MDT` in summer.\n",
+    "\n",
+    "### Convert Between Time Zones\n",
+    "\n",
+    "If you have data in UTC and wish to convert them to another time zone (in this example, US Mountain Time), you can call the [astimezone()](https://docs.python.org/3/library/datetime.html#datetime.datetime.astimezone) method with a `ZoneInfo` object. Start from a UTC-aware datetime (using `dt.timezone.utc`), then let `astimezone()` handle the conversion — including any DST offset automatically:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "utc = dt.datetime.now(dt.timezone.utc)\n",
+    "print(f'The UTC time is {utc.strftime('%B %d, %Y, %-I:%M%p')}.')\n",
+    "TZ_USMT = ZoneInfo('US/Mountain')\n",
+    "us_mt = utc.astimezone(TZ_USMT)\n",
+    "print(f'The {TZ_USMT} time is {us_mt.strftime('%B %d, %Y, %-I:%M%p')}.')"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "---"
+    "In the above example, we also use the `strftime()` method to format the date and time string in a human-friendly format."
    ]
   },
   {
@@ -507,7 +534,7 @@
     "\n",
     "The `datetime` module contains various classes for storing, converting, comparing, and formatting date and time data on the Gregorian calendar. We saw how we can parse data files with date and time strings into `dt.datetime` objects using the `dt.datetime.strptime()` method. We also saw how to perform arithmetic using date and time data; this uses the `dt.timedelta` class to represent intervals of time.\n",
     "\n",
-    "Finally, we looked at using the third-party [pytz](https://pypi.org/project/pytz/) module to handle time zone awareness and conversions.\n",
+    "Finally, we looked at using the [`zoneinfo`](https://docs.python.org/3/library/zoneinfo.html) module (Python Standard Library, version 3.9+) to handle time zone awareness and conversions using IANA time zone names, with automatic Daylight Saving Time support.\n",
     "\n",
     "### What's Next?\n",
     "\n",
@@ -520,24 +547,17 @@
    "source": [
     "## Resources and References\n",
     "\n",
-    "This page was based on and adapted from material in [Unidata's Python Training](https://unidata.github.io/python-training/python/times_and_dates/).\n",
+    "This page was based on and adapted from material designed at NSF Unidata.\n",
     "\n",
     "For further reading on these modules, take a look at the official documentation for:\n",
     "- [time](https://docs.python.org/3/library/time.html)\n",
     "- [datetime](https://docs.python.org/3/library/datetime.html)\n",
-    "- [pytz](https://pypi.org/project/pytz/)\n",
+    "- [zoneinfo](https://docs.python.org/3/library/zoneinfo.html)\n",
     "\n",
     "For more information on Python string formatting, try:\n",
     "- [Python string documentation](https://docs.python.org/3/library/string.html)\n",
     "- RealPython's [string formatting tutorial](https://realpython.com/python-string-formatting/) (nicely written)"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {