bpo-1100942: Add datetime.time.strptime and datetime.date.strptime

Add datetime.date.strptime and datetime.time.strptime.

Fix the documentation of _strptime._strptime, the documentation was
wrong, return a 3-tuple and not a 2-tuple

Co-authored-by: Alexander Belopolsky <[email protected]>
Co-authored-by: Amaury Forgeot d'Arc <[email protected]>
Co-authored-by: Berker Peksag <[email protected]>
Co-authored-by: Josh-sf <[email protected]>
Co-authored-by: Juarez Bochi <[email protected]>
Co-authored-by: Maciej Szulik <[email protected]>
Co-authored-by: Stéphane Wirtel <[email protected]>
Co-authored-by: Matheus Vieira Portela <[email protected]>

Author: 8 people

Doc/library/datetime.rst

@@ -435,6 +435,14 @@ Other constructors, all class methods:
    date.max.toordinal()``. For any date *d*, ``date.fromordinal(d.toordinal()) ==
    d``.
 
+.. classmethod:: date.strptime(date_string, format)
+
+   Return a :class:`date` corresponding to *date_string*, parsed according to
+   *format*. :exc:`ValueError` is raised if the date string and format can't be
+   parsed by `time.strptime`, or if it returns a value where the time part is
+   nonzero.
+
+   .. versionadded:: 3.8
 
 .. classmethod:: date.fromisoformat(date_string)
 
@@ -1424,6 +1432,19 @@ day, and subject to adjustment via a :class:`tzinfo` object.
    If an argument outside those ranges is given, :exc:`ValueError` is raised.  All
    default to ``0`` except *tzinfo*, which defaults to :const:`None`.
 
+
+Other constructors, all class methods:
+
+.. classmethod:: time.strptime(date_string, format)
+
+   Return a :class:`time` corresponding to *date_string, parsed according to
+   *format*. :exc:`ValueError` is raised if the date string and format can't be
+   parsed by `time.strptime`, if it returns a value which isn't a time tuple,
+   or if the date part is nonzero.
+
+   .. versionadded:: 3.8
+
+
 Class attributes:
 
 
@@ -2016,13 +2037,13 @@ Conversely, the :meth:`datetime.strptime` class method creates a
 corresponding format string. ``datetime.strptime(date_string, format)`` is
 equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``.
 
-For :class:`.time` objects, the format codes for year, month, and day should not
-be used, as time objects have no such values.  If they're used anyway, ``1900``
-is substituted for the year, and ``1`` for the month and day.
+The :meth:`date.strptime` class method creates a :class:`date` object from a
+string representing a date and a corresponding format string. :exc:`ValueError`
+raised if the format codes for hours, minutes, seconds, and microseconds are used.
 
-For :class:`date` objects, the format codes for hours, minutes, seconds, and
-microseconds should not be used, as :class:`date` objects have no such
-values.  If they're used anyway, ``0`` is substituted for them.
+The :meth:`.time.strptime` class method creates a :class:`.time` object from a
+string representing a time and a corresponding format string. :exc:`ValueError`
+raised if the format codes for year, month, and day are used.
 
 The full set of format codes supported varies across platforms, because Python
 calls the platform C library's :func:`strftime` function, and platform

Lib/_strptime.py

@@ -17,6 +17,7 @@
 from re import IGNORECASE
 from re import escape as re_escape
 from datetime import (date as datetime_date,
+                      datetime as datetime_datetime,
                       timedelta as datetime_timedelta,
                       timezone as datetime_timezone)
 from _thread import allocate_lock as _thread_allocate_lock
@@ -316,9 +317,9 @@ def _calc_julian_from_V(iso_year, iso_week, iso_weekday):
 
 
 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
+    """Return a 3-tuple consisting of a time struct and an int containing
     the number of microseconds based on the input string and the
-    format string."""
+    format string, and the GMT offset."""
 
     for index, arg in enumerate([data_string, format]):
         if not isinstance(arg, str):
@@ -565,6 +566,10 @@ def _strptime(data_string, format="%a %b %d %H:%M:%S %Y"):
             hour, minute, second,
             weekday, julian, tz, tzname, gmtoff), fraction, gmtoff_fraction
 
+date_specs = ('%a', '%A', '%b', '%B', '%c', '%d', '%j', '%m', '%U',
+              '%w', '%W', '%x', '%y', '%Y',)
+time_specs = ('%T', '%R', '%H', '%I', '%M', '%S', '%f', '%i', '%s',)
+
 def _strptime_time(data_string, format="%a %b %d %H:%M:%S %Y"):
     """Return a time struct based on the input string and the
     format string."""
@@ -586,3 +591,32 @@ def _strptime_datetime(cls, data_string, format="%a %b %d %H:%M:%S %Y"):
         args += (tz,)
 
     return cls(*args)
+
+def _strptime_datetime_date(data_string, format):
+    """Return a date based on the input string and the format string."""
+    if not format:
+        raise ValueError("Date format is not valid.")
+    msg = "'{!s}' {} not valid in date format specification."
+    if _check_invalid_datetime_specs(format, time_specs, msg):
+        _date = _strptime_datetime(datetime_datetime, data_string, format)
+        return _date.date()
+
+def _strptime_datetime_time(data_string, format):
+    """Return a time based on the input string and the format string."""
+    if not format:
+        raise ValueError("Date format is not valid.")
+    msg = "'{!s}' {} not valid in time format specification."
+    if _check_invalid_datetime_specs(format, date_specs, msg):
+        _time = _strptime_datetime(datetime_datetime, data_string, format)
+        return _time.time()
+
+def _check_invalid_datetime_specs(fmt, specs, msg):
+    found_invalid_specs = []
+    for spec in specs:
+        if spec in fmt:
+            found_invalid_specs.append(spec)
+    if found_invalid_specs:
+        suffix = "are" if len(found_invalid_specs) > 1 else "is"
+        raise ValueError(msg.format(", ".join(found_invalid_specs),
+                                    suffix))
+    return True

Lib/datetime.py

@@ -779,6 +779,7 @@ class date:
     fromtimestamp()
     today()
     fromordinal()
+    strptime()
 
     Operators:
 
@@ -859,6 +860,16 @@ def fromisoformat(cls, date_string):
             raise ValueError('Invalid isoformat string: %s' % date_string)
 
 
+    @classmethod
+    def strptime(cls, date_string, format):
+        """string, format -> new date instance parsed from a string.
+
+        >>> datetime.date.strptime('2012/07/20', '%Y/%m/%d')
+        datetime.date(2012, 7, 20)
+        """
+        import _strptime
+        return _strptime._strptime_datetime_date(date_string, format)
+
     # Conversions to string
 
     def __repr__(self):
@@ -1154,6 +1165,7 @@ class time:
     Constructors:
 
     __new__()
+    strptime()
 
     Operators:
 
@@ -1202,6 +1214,16 @@ def __new__(cls, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold
         self._fold = fold
         return self
 
+    @staticmethod
+    def strptime(time_string, format):
+        """string, format -> new time instance parsed from a string.
+
+        >>> datetime.time.strptime('10:40am', '%H:%M%p')
+        datetime.time(10, 40)
+        """
+        import _strptime
+        return _strptime._strptime_datetime_time(time_string, format)
+
     # Read-only field accessors
     @property
     def hour(self):
@@ -1856,7 +1878,11 @@ def __str__(self):
 
     @classmethod
     def strptime(cls, date_string, format):
-        'string, format -> new datetime parsed from a string (like time.strptime()).'
+        """string, format -> new datetime parsed from a string.
+
+        >>> datetime.datetime.strptime('2012/07/20 10:40am', '%Y/%m/%d %H:%M%p')
+        datetime.datetime(2012, 7, 20, 10, 40)
+        """
         import _strptime
         return _strptime._strptime_datetime(cls, date_string, format)
 

Lib/test/datetimetester.py

@@ -944,6 +944,23 @@ def test_delta_non_days_ignored(self):
         dt2 = dt - delta
         self.assertEqual(dt2, dt - days)
 
+    def test_strptime_valid_format(self):
+        tests = [(('2004-12-01', '%Y-%m-%d'),
+                  date(2004, 12, 1)),
+                 (('2004', '%Y'), date(2004, 1, 1)),]
+        for (date_string, date_format), expected in tests:
+            self.assertEqual(expected, date.strptime(date_string, date_format))
+
+    def test_strptime_invalid_format(self):
+        tests = [('2004-12-01 13:02:47.197',
+                  '%Y-%m-%d %H:%M:%S.%f'),
+                 ('01', '%M'),
+                 ('02', '%H'),]
+        for test in tests:
+            with self.assertRaises(ValueError):
+                date.strptime(test[0], test[1])
+
+
 class SubclassDate(date):
     sub_var = 1
 
@@ -2905,6 +2922,22 @@ def test_strftime(self):
         # A naive object replaces %z and %Z with empty strings.
         self.assertEqual(t.strftime("'%z' '%Z'"), "'' ''")
 
+    def test_strptime_invalid(self):
+        tests = [('2004-12-01 13:02:47.197',
+                  '%Y-%m-%d %H:%M:%S.%f'),
+                 ('2004-12-01', '%Y-%m-%d'),]
+        for date_string, date_format in tests:
+            with self.assertRaises(ValueError):
+                time.strptime(date_string, date_format)
+
+    def test_strptime_valid(self):
+        string = '13:02:47.197'
+        format = '%H:%M:%S.%f'
+        result, frac, gmtoff = _strptime._strptime(string, format)
+        expected = self.theclass(*(result[3:6] + (frac, )))
+        got = time.strptime(string, format)
+        self.assertEqual(expected, got)
+
     def test_format(self):
         t = self.theclass(1, 2, 3, 4)
         self.assertEqual(t.__format__(''), str(t))

Misc/NEWS.d/next/Core and Builtins/2018-02-07-10-55-58.bpo-1100942.md4agI.rst

@@ -0,0 +1 @@
+Add datetime.date.strptime and datetime.time.strptime class methods.

Modules/_datetimemodule.c

@@ -119,6 +119,10 @@ static PyTypeObject PyDateTime_DeltaType;
 static PyTypeObject PyDateTime_TimeType;
 static PyTypeObject PyDateTime_TZInfoType;
 static PyTypeObject PyDateTime_TimeZoneType;
+static PyObject *datetime_strptime(PyObject *cls, PyObject *args);
+static PyObject *datetime_getdate(PyDateTime_DateTime *self);
+static PyObject *datetime_gettime(PyDateTime_DateTime *self);
+
 
 static int check_tzinfo_subclass(PyObject *p);
 
@@ -2870,6 +2874,33 @@ date_fromordinal(PyObject *cls, PyObject *args)
     return result;
 }
 
+
+/* Return new date from time.strptime(). */
+static PyObject *
+date_strptime(PyObject *cls, PyObject *args)
+{
+    PyObject *date = NULL;
+    PyObject *datetime;
+
+    datetime = datetime_strptime((PyObject *)&PyDateTime_DateTimeType, args);
+
+    if (datetime == NULL)
+        return NULL;
+
+    if (DATE_GET_HOUR(datetime) ||
+        DATE_GET_MINUTE(datetime) ||
+        DATE_GET_SECOND(datetime) ||
+        DATE_GET_MICROSECOND(datetime))
+        PyErr_SetString(PyExc_ValueError,
+            "date.strptime value cannot have a time part");
+    else
+        date = datetime_getdate((PyDateTime_DateTime *)datetime);
+
+    Py_DECREF(datetime);
+    return date;
+}
+
+
 /* Return the new date from a string as generated by date.isoformat() */
 static PyObject *
 date_fromisoformat(PyObject *cls, PyObject *dtstr) {
@@ -3203,6 +3234,11 @@ static PyMethodDef date_methods[] = {
      PyDoc_STR("Current date or datetime:  same as "
                "self.__class__.fromtimestamp(time.time()).")},
 
+    {"strptime", (PyCFunction)date_strptime,     METH_VARARGS | METH_CLASS,
+     PyDoc_STR("string, format -> new date instance parsed from a string.\n\n"
+               ">>> datetime.date.strptime('2012/07/20', '%Y/%m/%d')\n"
+               "datetime.date(2012, 7, 20)")},
+
     /* Instance methods: */
 
     {"ctime",       (PyCFunction)date_ctime,        METH_NOARGS,
@@ -3916,6 +3952,49 @@ time_new(PyTypeObject *type, PyObject *args, PyObject *kw)
     return self;
 }
 
+
+/* Return new time from time.strptime(). */
+static PyObject *
+time_strptime(PyObject *cls, PyObject *args)
+{
+    PyObject *time = NULL;
+    PyObject *datetime;
+
+    static PyObject *emptyDatetime = NULL;
+
+    /* To ensure that the given string does not contain a date,
+     * compare with the result of an empty date string.
+     */
+    if (emptyDatetime == NULL) {
+        PyObject *emptyStringPair = Py_BuildValue("ss", "", "");
+        if (emptyStringPair == NULL)
+            return NULL;
+        emptyDatetime = datetime_strptime(
+            (PyObject *)&PyDateTime_DateTimeType,
+            emptyStringPair);
+        Py_DECREF(emptyStringPair);
+        if (emptyDatetime == NULL)
+            return NULL;
+    }
+
+    datetime = datetime_strptime((PyObject *)&PyDateTime_DateTimeType, args);
+
+    if (datetime == NULL)
+        return NULL;
+
+    if (GET_YEAR(datetime) != GET_YEAR(emptyDatetime)
+        || GET_MONTH(datetime) != GET_MONTH(emptyDatetime)
+        || GET_DAY(datetime) != GET_DAY(emptyDatetime))
+        PyErr_SetString(PyExc_ValueError,
+                        "time.strptime value cannot have a date part");
+    else
+        time = datetime_gettime((PyDateTime_DateTime *)datetime);
+
+    Py_DECREF(datetime);
+    return time;
+}
+
+
 /*
  * Destructor.
  */
@@ -4334,6 +4413,14 @@ time_reduce(PyDateTime_Time *self, PyObject *arg)
 }
 
 static PyMethodDef time_methods[] = {
+    /* Class methods: */
+
+    {"strptime", (PyCFunction)time_strptime, METH_VARARGS | METH_CLASS,
+     PyDoc_STR("string, format -> new time parsed from a string.\n\n"
+               ">>> datetime.time.strptime('10:40am', '%H:%M%p')\n"
+               "datetime.time(10, 40)")},
+
+    /* Instance methods: */
 
     {"isoformat",   (PyCFunction)time_isoformat,        METH_VARARGS | METH_KEYWORDS,
      PyDoc_STR("Return string in ISO 8601 format, [HH[:MM[:SS[.mmm[uuu]]]]]"
@@ -5891,8 +5978,10 @@ static PyMethodDef datetime_methods[] = {
 
     {"strptime", (PyCFunction)datetime_strptime,
      METH_VARARGS | METH_CLASS,
-     PyDoc_STR("string, format -> new datetime parsed from a string "
-               "(like time.strptime()).")},
+     PyDoc_STR("string, format -> new datetime parsed from a string.\n\n"
+               ">>> datetime.datetime.strptime('2012/07/20 10:40am', "
+               "'%Y/%m/%d %H:%M%p')\n"
+               "datetime.datetime(2012, 7, 20, 10, 40)")},
 
     {"combine", (PyCFunction)datetime_combine,
      METH_VARARGS | METH_KEYWORDS | METH_CLASS,