Add documentation for date(time).fromisocalendar

vstinner · Apr 29, 2019 · Feb 15, 2019 · Feb 17, 2019 · Feb 17, 2019 · Feb 17, 2019
commit 28c7fb27b9ba0e3378481631ce53dd9d79498073
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
@@ -458,6 +458,13 @@ Other constructors, all class methods:
   .. versionadded:: 3.7
 
 
+.. classmethod:: date.fromisocalendar(year, week, day)
+
+   Return a :class:`date` corresponding to the ISO calendar date specified by
+   year, week and day. This is the inverse of the function :meth:`date.isocalendar`.
+
+   .. versionadded:: 3.8
+
 
 Class attributes:
 
@@ -854,6 +861,16 @@ Other constructors, all class methods:
 
   .. versionadded:: 3.7
 
+
+.. classmethod:: datetime.fromisocalendar(year, week, day)
+
+   Return a :class:`datetime` corresponding to the ISO calendar date specified
+   by year, week and day. The non-date components of the datetime are populated
+   with their normal default values. This is the inverse of the function
+   :meth:`datetime.isocalendar`.
+
+   .. versionadded:: 3.8
+
 .. classmethod:: datetime.strptime(date_string, format)
 
    Return a :class:`.datetime` corresponding to *date_string*, parsed according to

diff --git a/Lib/datetime.py b/Lib/datetime.py
@@ -886,6 +886,9 @@ def fromisoformat(cls, date_string):
 
     @classmethod
     def fromisocalendar(cls, year, week, day):
+        """Construct a date from the ISO year, week number and weekday.
+
+        This is the inverse of the date.isocalendar() function"""
         # Year is bounded this way because 9999-12-31 is (9999, 52, 5)
         if not 0 < year < 10000:
             raise ValueError(f"Year is out of range: {year}")

diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c
@@ -3359,8 +3359,9 @@ static PyMethodDef date_methods[] = {
 
      {"fromisocalendar", (PyCFunction)(void(*)(void))date_fromisocalendar,
       METH_VARARGS | METH_KEYWORDS | METH_CLASS,
-      PyDoc_STR("int, int, int -> Construct a date from the "
-                "output of date.isocalendar()")},
+      PyDoc_STR("int, int, int -> Construct a date from the ISO year, week "
+                "number and weekday.\n\n"
+                "This is the inverse of the date.isocalendar() function")},
 
     {"today",         (PyCFunction)date_today,   METH_NOARGS | METH_CLASS,
      PyDoc_STR("Current date or datetime:  same as "