Merge branch 'python:main' into pythongh-82054

.github/workflows/doc.yml

@@ -79,6 +79,26 @@ jobs:
  # Build docs with the '-n' (nit-picky) option, convert warnings to errors (-W)
  make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going" html 2>&1
 
+ # This build doesn't use problem matchers or check annotations
+ # It also does not run 'make check', as sphinx-lint is not installed into the
+ # environment.
+ build_doc_oldest_supported_sphinx:
+ name: 'Docs (Oldest Sphinx)'
+ runs-on: ubuntu-latest
+ timeout-minutes: 60
+ steps:
+ - uses: actions/checkout@v3
+ - name: 'Set up Python'
+ uses: actions/setup-python@v4
+ with:
+ python-version: '3.11' # known to work with Sphinx 3.2
+ cache: 'pip'
+ cache-dependency-path: 'Doc/requirements-oldest-sphinx.txt'
+ - name: 'Install build dependencies'
+ run: make -C Doc/ venv REQUIREMENTS="requirements-oldest-sphinx.txt"
+ - name: 'Build HTML documentation'
+ run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
+
  # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
  doctest:
  name: 'Doctest'

Doc/Makefile

@@ -13,6 +13,7 @@ JOBS = auto
 PAPER =
 SOURCES =
 DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py)
+REQUIREMENTS = requirements.txt
 SPHINXERRORHANDLING = -W
 
 # Internal variables.
@@ -154,8 +155,8 @@ venv:
  echo "To recreate it, remove it first with \`make clean-venv'."; \
  else \
  $(PYTHON) -m venv $(VENVDIR); \
- $(VENVDIR)/bin/python3 -m pip install -U pip setuptools; \
- $(VENVDIR)/bin/python3 -m pip install -r requirements.txt; \
+ $(VENVDIR)/bin/python3 -m pip install --upgrade pip; \
+ $(VENVDIR)/bin/python3 -m pip install -r $(REQUIREMENTS); \
  echo "The venv has been created in the $(VENVDIR) directory"; \
  fi
 

Doc/library/datetime.rst

@@ -896,6 +896,10 @@ Other constructors, all class methods:
  in UTC. As such, the recommended way to create an object representing the
  current time in UTC is by calling ``datetime.now(timezone.utc)``.
 
+ .. deprecated:: 3.12
+
+ Use :meth:`datetime.now` with :attr:`UTC` instead.
+
 
 .. classmethod:: datetime.fromtimestamp(timestamp, tz=None)
 
@@ -964,6 +968,10 @@ Other constructors, all class methods:
  :c:func:`gmtime` function. Raise :exc:`OSError` instead of
  :exc:`ValueError` on :c:func:`gmtime` failure.
 
+ .. deprecated:: 3.12
+
+ Use :meth:`datetime.fromtimestamp` with :attr:`UTC` instead.
+
 
 .. classmethod:: datetime.fromordinal(ordinal)
 

Doc/library/sqlite3.rst

@@ -310,7 +310,7 @@ Module functions
  to avoid data corruption.
  See :attr:`threadsafety` for more information.
 
- :param Connection factory:
+ :param ~sqlite3.Connection factory:
  A custom subclass of :class:`Connection` to create the connection with,
  if not the default :class:`Connection` class.
 
@@ -337,7 +337,7 @@ Module functions
  The default will change to ``False`` in a future Python release.
  :type autocommit: bool
 
- :rtype: Connection
+ :rtype: ~sqlite3.Connection
 
  .. audit-event:: sqlite3.connect database sqlite3.connect
  .. audit-event:: sqlite3.connect/handle connection_handle sqlite3.connect
@@ -1129,7 +1129,7 @@ Connection objects
  Works even if the database is being accessed by other clients
  or concurrently by the same connection.
 
- :param Connection target:
+ :param ~sqlite3.Connection target:
  The database connection to save the backup to.
 
  :param int pages:

Doc/requirements-oldest-sphinx.txt

@@ -0,0 +1,38 @@
+# Requirements to build the Python documentation, for the oldest supported
+# Sphinx version.
+#
+# We pin Sphinx and all of its dependencies to ensure a consistent environment.
+
+blurb
+python-docs-theme>=2022.1
+
+# Generated from:
+# pip install "Sphinx~=3.2.0" "docutils<0.17" "Jinja2<3" "MarkupSafe<2"
+# pip freeze
+#
+# Sphinx 3.2 comes from ``needs_sphinx = '3.2'`` in ``Doc/conf.py``.
+# Docutils<0.17, Jinja2<3, and MarkupSafe<2 are additionally specified as
+# Sphinx 3.2 is incompatible with newer releases of these packages.
+
+Sphinx==3.2.1
+alabaster==0.7.13
+Babel==2.12.1
+certifi==2022.12.7
+charset-normalizer==3.1.0
+colorama==0.4.6
+docutils==0.16
+idna==3.4
+imagesize==1.4.1
+Jinja2==2.11.3
+MarkupSafe==1.1.1
+packaging==23.1
+Pygments==2.15.1
+requests==2.29.0
+snowballstemmer==2.2.0
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+urllib3==1.26.15

Lib/_strptime.py

@@ -290,22 +290,6 @@ def _calc_julian_from_U_or_W(year, week_of_year, day_of_week, week_starts_Mon):
  return 1 + days_to_week + day_of_week
 
 
-def _calc_julian_from_V(iso_year, iso_week, iso_weekday):
- """Calculate the Julian day based on the ISO 8601 year, week, and weekday.
- ISO weeks start on Mondays, with week 01 being the week containing 4 Jan.
- ISO week days range from 1 (Monday) to 7 (Sunday).
- """
- correction = datetime_date(iso_year, 1, 4).isoweekday() + 3
- ordinal = (iso_week * 7) + iso_weekday - correction
- # ordinal may be negative or 0 now, which means the date is in the previous
- # calendar year
- if ordinal < 1:
- ordinal += datetime_date(iso_year, 1, 1).toordinal()
- iso_year -= 1
- ordinal -= datetime_date(iso_year, 1, 1).toordinal()
- return iso_year, ordinal
-
-
 def _strptime(data_string, format="%a %b %d %H:%M:%S %Y"):
  """Return a 2-tuple consisting of a time struct and an int containing
  the number of microseconds based on the input string and the
@@ -483,7 +467,8 @@ def _strptime(data_string, format="%a %b %d %H:%M:%S %Y"):
  else:
  tz = value
  break
- # Deal with the cases where ambiguities arize
+
+ # Deal with the cases where ambiguities arise
  # don't assume default values for ISO week/year
  if year is None and iso_year is not None:
  if iso_week is None or weekday is None:
@@ -511,7 +496,6 @@ def _strptime(data_string, format="%a %b %d %H:%M:%S %Y"):
  elif year is None:
  year = 1900
 
-
  # If we know the week of the year and what day of that week, we can figure
  # out the Julian day of the year.
  if julian is None and weekday is not None:
@@ -520,7 +504,10 @@ def _strptime(data_string, format="%a %b %d %H:%M:%S %Y"):
  julian = _calc_julian_from_U_or_W(year, week_of_year, weekday,
  week_starts_Mon)
  elif iso_year is not None and iso_week is not None:
- year, julian = _calc_julian_from_V(iso_year, iso_week, weekday + 1)
+ datetime_result = datetime_date.fromisocalendar(iso_year, iso_week, weekday + 1)
+ year = datetime_result.year
+ month = datetime_result.month
+ day = datetime_result.day
  if julian is not None and julian <= 0:
  year -= 1
  yday = 366 if calendar.isleap(year) else 365

Lib/datetime.py

@@ -1801,6 +1801,13 @@ def fromtimestamp(cls, timestamp, tz=None):
  @classmethod
  def utcfromtimestamp(cls, t):
  """Construct a naive UTC datetime from a POSIX timestamp."""
+ import warnings
+ warnings.warn("datetime.utcfromtimestamp() is deprecated and scheduled "
+ "for removal in a future version. Use timezone-aware "
+ "objects to represent datetimes in UTC: "
+ "datetime.fromtimestamp(t, datetime.UTC).",
+ DeprecationWarning,
+ stacklevel=2)
  return cls._fromtimestamp(t, True, None)
 
  @classmethod
@@ -1812,8 +1819,15 @@ def now(cls, tz=None):
  @classmethod
  def utcnow(cls):
  "Construct a UTC datetime from time.time()."
+ import warnings
+ warnings.warn("datetime.utcnow() is deprecated and scheduled for "
+ "removal in a future version. Instead, Use timezone-aware "
+ "objects to represent datetimes in UTC: "
+ "datetime.now(datetime.UTC).",
+ DeprecationWarning,
+ stacklevel=2)
  t = _time.time()
- return cls.utcfromtimestamp(t)
+ return cls._fromtimestamp(t, True, None)
 
  @classmethod
  def combine(cls, date, time, tzinfo=True):

Lib/email/utils.py

@@ -143,13 +143,13 @@ def formatdate(timeval=None, localtime=False, usegmt=False):
  # 2822 requires that day and month names be the English abbreviations.
  if timeval is None:
  timeval = time.time()
- if localtime or usegmt:
- dt = datetime.datetime.fromtimestamp(timeval, datetime.timezone.utc)
- else:
- dt = datetime.datetime.utcfromtimestamp(timeval)
+ dt = datetime.datetime.fromtimestamp(timeval, datetime.timezone.utc)
+
  if localtime:
  dt = dt.astimezone()
  usegmt = False
+ elif not usegmt:
+ dt = dt.replace(tzinfo=None)
  return format_datetime(dt, usegmt)
 
 def format_datetime(dt, usegmt=False):

Lib/http/cookiejar.py

@@ -104,9 +104,9 @@ def time2isoz(t=None):
 
  """
  if t is None:
- dt = datetime.datetime.utcnow()
+ dt = datetime.datetime.now(tz=datetime.UTC)
  else:
- dt = datetime.datetime.utcfromtimestamp(t)
+ dt = datetime.datetime.fromtimestamp(t, tz=datetime.UTC)
  return "%04d-%02d-%02d %02d:%02d:%02dZ" % (
  dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second)
 
@@ -122,9 +122,9 @@ def time2netscape(t=None):
 
  """
  if t is None:
- dt = datetime.datetime.utcnow()
+ dt = datetime.datetime.now(tz=datetime.UTC)
  else:
- dt = datetime.datetime.utcfromtimestamp(t)
+ dt = datetime.datetime.fromtimestamp(t, tz=datetime.UTC)
  return "%s, %02d-%s-%04d %02d:%02d:%02d GMT" % (
  DAYS[dt.weekday()], dt.day, MONTHS[dt.month-1],
  dt.year, dt.hour, dt.minute, dt.second)